chore: sync .mokogitea/workflows/pr-check.yml from moko-platform [skip ci]

Allows release workflows to skip updates.xml generation and sync.
This decouples release creation from update stream management,
enabling updates.xml to be managed externally (e.g. Gitea Pages).

Authored-by: Moko Consulting
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.mokogitea/workflows/ci-platform.yml

@@ -412,12 +412,6 @@ jobs:
     if: always()
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          sparse-checkout: automation/ci-issue-reporter.sh
-          sparse-checkout-cone-mode: false
-
       - name: Check gate results
         run: |
           {
@@ -443,46 +437,3 @@ jobs:
             echo "::error::One or more CI gates failed"
             exit 1
           fi
-
-      - name: "File issues for failed gates"
-        if: >-
-          always() &&
-          (needs.code-quality.result == 'failure' ||
-           needs.tests.result == 'failure' ||
-           needs.self-health.result == 'failure' ||
-           needs.governance.result == 'failure' ||
-           needs.templates.result == 'failure')
-        env:
-          GITEA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
-          GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
-        run: |
-          chmod +x automation/ci-issue-reporter.sh
-          REPORTER="./automation/ci-issue-reporter.sh"
-          WF="Platform CI"
-
-          report_gate() {
-            local gate="$1" result="$2" details="$3"
-            if [ "$result" = "failure" ]; then
-              "$REPORTER" --gate "$gate" --details "$details" --workflow "$WF" --severity error
-            fi
-          }
-
-          report_gate "Code Quality" \
-            "${{ needs.code-quality.result }}" \
-            "PHPCS (PSR-12), PHPStan, or PHP syntax checks failed. Run \`composer check\` locally to reproduce."
-
-          report_gate "Unit Tests" \
-            "${{ needs.tests.result }}" \
-            "PHPUnit tests failed on one or more PHP versions (8.1, 8.2, 8.3). Run \`vendor/bin/phpunit --testdox\` locally."
-
-          report_gate "Self-Health" \
-            "${{ needs.self-health.result }}" \
-            "Self-health score fell below the 80% threshold. Run \`php bin/moko health -- --path .\` locally."
-
-          report_gate "Governance" \
-            "${{ needs.governance.result }}" \
-            "Governance checks failed (license headers, secrets, or version consistency). Check the CI run summary for specifics."
-
-          report_gate "Template Integrity" \
-            "${{ needs.templates.result }}" \
-            "Workflow or gitignore templates failed YAML validation or are missing required entries."

.mokogitea/workflows/pre-release.yml

@@ -7,7 +7,7 @@
 # INGROUP: moko-platform.Release
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /templates/workflows/universal/pre-release.yml.template
-# VERSION: 05.01.00
+# VERSION: 09.23.00
 # BRIEF: Manual pre-release -- builds dev/alpha/beta/rc packages from any branch
 
 name: "Universal: Pre-Release"
@@ -17,10 +17,6 @@ on:
     types: [closed]
     branches:
       - dev
-  pull_request_target:
-    types: [synchronize, opened, reopened]
-    branches:
-      - main
   workflow_dispatch:
     inputs:
       stability:
@@ -47,8 +43,7 @@ jobs:
     runs-on: release
     if: >-
       github.event_name == 'workflow_dispatch' ||
-      (github.event_name == 'pull_request' && github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev') ||
-      (github.event_name == 'pull_request_target' && github.event.pull_request.base.ref == 'main')
+      (github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev')
 
     steps:
       - name: Checkout
@@ -56,7 +51,6 @@ jobs:
         with:
           fetch-depth: 0
           token: ${{ secrets.MOKOGITEA_TOKEN }}
-          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || '' }}
 
       - name: Setup moko-platform tools
         env:
@@ -66,7 +60,7 @@ jobs:
           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
-          # Always fetch latest CLI tools — never use stale cache from previous runs
+          # Always fetch latest CLI tools — never use stale cache from previous runs
           rm -rf /tmp/moko-platform-api
           git clone --depth 1 --branch main --quiet \
             "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
@@ -82,37 +76,24 @@ jobs:
       - name: Resolve metadata and bump version
         id: meta
         run: |
-          # Auto-detect stability: RC for PRs targeting main, else use input or default to development
-          if [ "${{ github.event_name }}" = "pull_request_target" ] && [ "${{ github.event.pull_request.base.ref }}" = "main" ]; then
-            STABILITY="release-candidate"
-          else
-            STABILITY="${{ inputs.stability || 'development' }}"
-          fi
+          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" ;;
+            development)        TAG="development" ;;
+            alpha)              TAG="alpha" ;;
+            beta)               TAG="beta" ;;
+            release-candidate)  TAG="release-candidate" ;;
           esac
 
-          # Read current version (bump already handled by push workflow)
-          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null)
-          [ -z "$VERSION" ] && VERSION="00.00.01"
-
-          # Strip any existing suffix from version before applying stability
-          VERSION=$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
-
+          # Set stability suffix, bump preserves it, fix consistency
           php ${MOKO_CLI}/version_set_platform.php \
-            --path . --version "$VERSION" --branch "${{ github.ref_name }}" --stability "$STABILITY" 2>/dev/null || true
-
-          # Verify version consistency across all files
+            --path . --version "$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo '00.00.01')" \
+            --branch "${{ github.ref_name }}" --stability "$STABILITY" 2>/dev/null || true
           php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
 
-          # Update VERSION variable with suffix
-          if [ -n "$SUFFIX" ]; then
-            VERSION="${VERSION}${SUFFIX}"
-          fi
+          # Read final version (includes suffix, e.g. 01.02.15-dev)
+          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null)
+          [ -z "$VERSION" ] && VERSION="00.00.01"
 
           # Commit version bump
           git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
@@ -137,12 +118,11 @@ jobs:
 
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
-          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
           echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
           echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
           echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"
 
-          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
+          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION} ==="
 
       - name: Create release
         id: release
@@ -155,21 +135,6 @@ jobs:
             --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
             --repo "${GITEA_REPO}" --branch dev --prerelease
 
-      - name: Ensure prerelease flag
-        run: |
-          TAG="${{ steps.meta.outputs.tag }}"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          # Get release ID by tag and force prerelease=true
-          RELEASE_ID=$(curl -s "${API_BASE}/releases/tags/${TAG}" \
-            -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" | jq -r '.id // empty')
-          if [ -n "$RELEASE_ID" ]; then
-            curl -s -X PATCH "${API_BASE}/releases/${RELEASE_ID}" \
-              -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \
-              -H "Content-Type: application/json" \
-              -d '{"prerelease": true}'
-            echo "Marked release ${TAG} (id=${RELEASE_ID}) as prerelease"
-          fi
-
       - name: Build package and upload
         id: package
         run: |

automation/ci-issue-reporter.sh

@@ -1,237 +0,0 @@
-#!/usr/bin/env bash
-# ============================================================================
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-#
-# FILE INFORMATION
-# DEFGROUP: Automation.CI
-# INGROUP: moko-platform.Automation
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
-# PATH: /automation/ci-issue-reporter.sh
-# VERSION: 09.23.00
-# BRIEF: Creates or updates a Gitea issue when a CI gate fails.
-#        Deduplicates by searching open issues with the "ci-auto" label
-#        whose title matches the gate. If a matching issue exists, a comment
-#        is appended instead of opening a duplicate.
-# ============================================================================
-
-set -euo pipefail
-
-# ── Defaults ────────────────────────────────────────────────────────────────
-GITEA_URL="${GITEA_URL:-https://git.mokoconsulting.tech}"
-GITEA_TOKEN="${GITEA_TOKEN:-}"
-REPO="${GITHUB_REPOSITORY:-}"
-RUN_URL="${GITHUB_SERVER_URL:-${GITEA_URL}}/${REPO}/actions/runs/${GITHUB_RUN_ID:-0}"
-LABEL_NAME="ci-auto"
-LABEL_COLOR="#e11d48"
-
-GATE=""
-DETAILS=""
-SEVERITY="error"
-WORKFLOW=""
-
-# ── Parse arguments ─────────────────────────────────────────────────────────
-usage() {
-  cat <<EOF
-Usage: ci-issue-reporter.sh --gate NAME --details TEXT [OPTIONS]
-
-Required:
-  --gate      CI gate name (e.g. "Code Quality", "Self-Health")
-  --details   Human-readable failure description
-
-Optional:
-  --severity  "error" (default) or "warning"
-  --workflow  Workflow name for the issue title
-  --repo      owner/repo (default: \$GITHUB_REPOSITORY)
-  --run-url   URL to the CI run (auto-detected from env)
-  --token     Gitea API token (default: \$GITEA_TOKEN)
-  --url       Gitea base URL (default: \$GITEA_URL)
-EOF
-  exit 1
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --gate)     GATE="$2";       shift 2 ;;
-    --details)  DETAILS="$2";    shift 2 ;;
-    --severity) SEVERITY="$2";   shift 2 ;;
-    --workflow) WORKFLOW="$2";   shift 2 ;;
-    --repo)     REPO="$2";      shift 2 ;;
-    --run-url)  RUN_URL="$2";   shift 2 ;;
-    --token)    GITEA_TOKEN="$2"; shift 2 ;;
-    --url)      GITEA_URL="$2"; shift 2 ;;
-    -h|--help)  usage ;;
-    *)          echo "Unknown option: $1"; usage ;;
-  esac
-done
-
-[[ -z "$GATE" ]]         && { echo "ERROR: --gate is required"; usage; }
-[[ -z "$DETAILS" ]]      && { echo "ERROR: --details is required"; usage; }
-[[ -z "$GITEA_TOKEN" ]]  && { echo "ERROR: GITEA_TOKEN not set"; exit 1; }
-[[ -z "$REPO" ]]         && { echo "ERROR: GITHUB_REPOSITORY not set"; exit 1; }
-
-API="${GITEA_URL}/api/v1/repos/${REPO}"
-
-# ── Build title ─────────────────────────────────────────────────────────────
-if [[ -n "$WORKFLOW" ]]; then
-  TITLE="[CI] ${WORKFLOW}: ${GATE} failed"
-else
-  TITLE="[CI] ${GATE} failed"
-fi
-
-# ── Ensure label exists ─────────────────────────────────────────────────────
-ensure_label() {
-  local exists
-  exists=$(curl -sf -o /dev/null -w '%{http_code}' \
-    -H "Authorization: token ${GITEA_TOKEN}" \
-    "${API}/labels" 2>/dev/null || echo "000")
-
-  if [[ "$exists" == "200" ]]; then
-    # Check if label already exists
-    local found
-    found=$(curl -sf \
-      -H "Authorization: token ${GITEA_TOKEN}" \
-      "${API}/labels" 2>/dev/null \
-      | grep -o "\"name\":\"${LABEL_NAME}\"" || true)
-
-    if [[ -z "$found" ]]; then
-      curl -sf -X POST \
-        -H "Authorization: token ${GITEA_TOKEN}" \
-        -H "Content-Type: application/json" \
-        "${API}/labels" \
-        -d "{\"name\":\"${LABEL_NAME}\",\"color\":\"${LABEL_COLOR}\",\"description\":\"Auto-created by CI issue reporter\"}" \
-        > /dev/null 2>&1 || true
-    fi
-  fi
-}
-
-# ── Search for existing open issue ──────────────────────────────────────────
-find_existing_issue() {
-  # URL-encode the gate name for the query
-  local query
-  query=$(printf '%s' "[CI] ${GATE}" | sed 's/ /%20/g; s/\[/%5B/g; s/\]/%5D/g')
-
-  local response
-  response=$(curl -sf \
-    -H "Authorization: token ${GITEA_TOKEN}" \
-    "${API}/issues?type=issues&state=open&labels=${LABEL_NAME}&q=${query}&limit=5" \
-    2>/dev/null || echo "[]")
-
-  # Extract the first matching issue number
-  echo "$response" \
-    | grep -oP '"number":\s*\K[0-9]+' \
-    | head -1
-}
-
-# ── Build issue body ────────────────────────────────────────────────────────
-build_body() {
-  local severity_badge
-  if [[ "$SEVERITY" == "error" ]]; then
-    severity_badge="**Severity:** Error"
-  else
-    severity_badge="**Severity:** Warning"
-  fi
-
-  cat <<BODY
-## CI Gate Failure: ${GATE}
-
-${severity_badge}
-**Workflow:** ${WORKFLOW:-unknown}
-**Branch:** ${GITHUB_REF_NAME:-unknown}
-**Commit:** \`${GITHUB_SHA:0:8}\`
-**Run:** [View CI run](${RUN_URL})
-
-### Details
-
-${DETAILS}
-
-### Resolution
-
-Fix the issue described above and push a new commit. This issue will be closed automatically when the gate passes, or can be closed manually.
-
----
-*Auto-created by [ci-issue-reporter](${GITEA_URL}/${REPO}/src/branch/main/automation/ci-issue-reporter.sh)*
-BODY
-}
-
-# ── Build comment body (for existing issues) ────────────────────────────────
-build_comment() {
-  cat <<COMMENT
-### CI failure recurrence
-
-**Branch:** ${GITHUB_REF_NAME:-unknown}
-**Commit:** \`${GITHUB_SHA:0:8}\`
-**Run:** [View CI run](${RUN_URL})
-
-${DETAILS}
-COMMENT
-}
-
-# ── Main ────────────────────────────────────────────────────────────────────
-ensure_label
-
-EXISTING=$(find_existing_issue)
-
-if [[ -n "$EXISTING" ]]; then
-  # Append comment to existing issue
-  COMMENT_BODY=$(build_comment)
-  COMMENT_JSON=$(printf '%s' "$COMMENT_BODY" | python3 -c "
-import sys, json
-print(json.dumps({'body': sys.stdin.read()}))" 2>/dev/null)
-
-  HTTP=$(curl -sf -o /dev/null -w '%{http_code}' -X POST \
-    -H "Authorization: token ${GITEA_TOKEN}" \
-    -H "Content-Type: application/json" \
-    "${API}/issues/${EXISTING}/comments" \
-    -d "${COMMENT_JSON}" 2>/dev/null || echo "000")
-
-  if [[ "$HTTP" == "201" ]]; then
-    echo "Commented on existing issue #${EXISTING}"
-  else
-    echo "WARNING: Failed to comment on issue #${EXISTING} (HTTP ${HTTP})"
-  fi
-else
-  # Create new issue
-  ISSUE_BODY=$(build_body)
-  ISSUE_JSON=$(python3 -c "
-import sys, json
-body = sys.stdin.read()
-print(json.dumps({
-    'title': sys.argv[1],
-    'body': body,
-    'labels': []
-}))" "$TITLE" <<< "$ISSUE_BODY" 2>/dev/null)
-
-  # Create the issue
-  RESPONSE=$(curl -sf -X POST \
-    -H "Authorization: token ${GITEA_TOKEN}" \
-    -H "Content-Type: application/json" \
-    "${API}/issues" \
-    -d "${ISSUE_JSON}" 2>/dev/null || echo "{}")
-
-  ISSUE_NUM=$(echo "$RESPONSE" | grep -oP '"number":\s*\K[0-9]+' | head -1)
-
-  if [[ -n "$ISSUE_NUM" ]]; then
-    # Apply label (separate call — more reliable across Gitea versions)
-    LABEL_ID=$(curl -sf \
-      -H "Authorization: token ${GITEA_TOKEN}" \
-      "${API}/labels" 2>/dev/null \
-      | grep -oP "\"id\":\s*\K[0-9]+(?=[^}]*\"name\":\s*\"${LABEL_NAME}\")" \
-      | head -1 || true)
-
-    if [[ -n "$LABEL_ID" ]]; then
-      curl -sf -X POST \
-        -H "Authorization: token ${GITEA_TOKEN}" \
-        -H "Content-Type: application/json" \
-        "${API}/issues/${ISSUE_NUM}/labels" \
-        -d "{\"labels\":[${LABEL_ID}]}" \
-        > /dev/null 2>&1 || true
-    fi
-
-    echo "Created issue #${ISSUE_NUM}: ${TITLE}"
-  else
-    echo "WARNING: Failed to create issue"
-    echo "Response: ${RESPONSE}"
-  fi
-fi

automation/push_files.php

@@ -230,8 +230,7 @@ class PushFiles extends CliFramework
     {
         // Read platform from repo's .mokogitea/manifest.xml via API
         try {
-            $fileInfo = $this->adapter->getFileContents($org, $repo, '.mokogitea/manifest.xml', 'main');
-            $manifestData = isset($fileInfo['content']) ? base64_decode($fileInfo['content']) : '';
+            $manifestData = $this->adapter->getFileContent($org, $repo, '.mokogitea/manifest.xml', 'main');
             if (!empty($manifestData)) {
                 $xml = @simplexml_load_string($manifestData);
                 if ($xml !== false) {

cli/release_package.php

@@ -230,31 +230,12 @@ class ReleasePackageCli extends CliFramework
                 $subName = basename($pkgDir);
                 $subZipPath = "{$outputDir}/{$subName}.zip";
 
-                // If sub-package is a full repo checkout (e.g. git submodule),
-                // look for a src/ subdirectory containing a Joomla manifest XML
-                // and zip that instead of the repo root.
-                $subSourceDir = $pkgDir;
-                $srcCandidate = "{$pkgDir}/src";
-                if (is_dir($srcCandidate)) {
-                    $srcManifests = array_merge(
-                        glob("{$srcCandidate}/*.xml") ?: [],
-                        glob("{$srcCandidate}/pkg_*.xml") ?: []
-                    );
-                    foreach ($srcManifests as $mf) {
-                        if (strpos(file_get_contents($mf) ?: '', '<extension') !== false) {
-                            $subSourceDir = $srcCandidate;
-                            echo "  Sub-package {$subName}: using src/ entry-point\n";
-                            break;
-                        }
-                    }
-                }
-
                 $subZip = new \ZipArchive();
                 if ($subZip->open($subZipPath, \ZipArchive::CREATE | \ZipArchive::OVERWRITE) !== true) {
                     $this->log('ERROR', "Failed to create sub-package ZIP: {$subZipPath}");
                     continue;
                 }
-                $this->addDirToZip($subZip, $subSourceDir, '', $this->excludePatterns);
+                $this->addDirToZip($subZip, $pkgDir, '', $this->excludePatterns);
                 $subZip->close();
 
                 $zip->addFile($subZipPath, "packages/{$subName}.zip");

cli/release_publish.php

@@ -34,6 +34,7 @@ class ReleasePublishCli extends CliFramework
         $this->addArgument('--org', 'Organization', '');
         $this->addArgument('--repo', 'Repository name', '');
         $this->addArgument('--repo-url', 'Repository URL for git auth', '');
+        $this->addArgument('--skip-update-stream', 'Skip updates.xml generation and sync (managed externally)', false);
     }
 
     protected function run(): int
@@ -46,7 +47,8 @@ class ReleasePublishCli extends CliFramework
         $giteaUrl  = $this->getArgument('--gitea-url') ?: (getenv('GITEA_URL') ?: 'https://git.mokoconsulting.tech');
         $org       = $this->getArgument('--org') ?: (getenv('GITEA_ORG') ?: '');
         $repo      = $this->getArgument('--repo') ?: (getenv('GITEA_REPO') ?: '');
-        $repoUrl   = $this->getArgument('--repo-url');
+        $repoUrl           = $this->getArgument('--repo-url');
+        $skipUpdateStream  = $this->getArgument('--skip-update-stream');
 
         if (empty($stability) || empty($token)) {
             $this->log('ERROR', "Usage: release_publish.php --stability <dev|alpha|beta|rc|stable> --token TOKEN [options]");
@@ -295,66 +297,71 @@ class ReleasePublishCli extends CliFramework
         // -- Step 4: No lesser stream copies --
         echo "\n--- Step 4: Skipped (no lesser stream copies) ---\n";
 
-        // -- Step 5: Update ONLY this stream in updates.xml --
-        echo "\n--- Step 5: Update {$stability} stream in updates.xml ---\n";
-        $streamsToWrite = [$stability];
+        if ($skipUpdateStream) {
+            echo "\n--- Step 5: Skipped (--skip-update-stream) ---\n";
+            echo "\n--- Step 6: Skipped (--skip-update-stream) ---\n";
+        } else {
+            // -- Step 5: Update ONLY this stream in updates.xml --
+            echo "\n--- Step 5: Update {$stability} stream in updates.xml ---\n";
+            $streamsToWrite = [$stability];
 
-        foreach ($streamsToWrite as $stream) {
-            $streamVersion = $releaseVersion;
-            $shaFlag = !empty($sha256) ? "--sha {$sha256}" : '';
+            foreach ($streamsToWrite as $stream) {
+                $streamVersion = $releaseVersion;
+                $shaFlag = !empty($sha256) ? "--sha {$sha256}" : '';
+
+                echo "  Writing {$stream} stream: {$streamVersion}\n";
+                if (!$this->dryRun) {
+                    passthru("{$php} {$cli}/updates_xml_build.php --path " . escapeshellarg($path)
+                        . " --version " . escapeshellarg($streamVersion)
+                        . " --stability " . escapeshellarg($stream)
+                        . " --gitea-url " . escapeshellarg($giteaUrl)
+                        . " --org " . escapeshellarg($org)
+                        . " --repo " . escapeshellarg($repo)
+                        . " {$shaFlag} 2>&1");
+                }
+            }
+
+            // -- Step 6: Commit updates.xml and sync to all branches --
+            echo "\n--- Step 6: Commit and sync updates.xml ---\n";
+            $root = realpath($path) ?: $path;
 
-            echo "  Writing {$stream} stream: {$streamVersion}\n";
             if (!$this->dryRun) {
-                passthru("{$php} {$cli}/updates_xml_build.php --path " . escapeshellarg($path)
-                    . " --version " . escapeshellarg($streamVersion)
-                    . " --stability " . escapeshellarg($stream)
+                $cdX = PHP_OS_FAMILY === 'Windows' ? "cd /d " : "cd ";
+                $cdRt = $cdX . escapeshellarg($root);
+                $diffCheck = trim((string) @shell_exec(
+                    $cdRt . " && git diff --quiet updates.xml"
+                    . " 2>&1 && echo clean || echo dirty"
+                ));
+                if ($diffCheck === 'dirty') {
+                    @shell_exec($cdRt . " && git add updates.xml");
+                    $chMsg = "chore: update channels for"
+                        . " {$releaseVersion} [skip ci]";
+                    @shell_exec(
+                        $cdRt . " && git commit -m "
+                        . escapeshellarg($chMsg)
+                        . " --author=\"gitea-actions[bot]"
+                        . " <gitea-actions[bot]@mokoconsulting.tech>\""
+                    );
+                    @shell_exec(
+                        $cdRt . " && git push origin "
+                        . escapeshellarg($branch) . " 2>&1"
+                    );
+                    echo "  Committed updates.xml\n";
+                }
+
+                // Sync to all branches
+                passthru("{$php} {$cli}/updates_xml_sync.php --path " . escapeshellarg($path)
+                    . " --current " . escapeshellarg($branch) . " --all"
+                    . " --version " . escapeshellarg($releaseVersion)
+                    . " --token " . escapeshellarg($token)
                     . " --gitea-url " . escapeshellarg($giteaUrl)
                     . " --org " . escapeshellarg($org)
-                    . " --repo " . escapeshellarg($repo)
-                    . " {$shaFlag} 2>&1");
+                    . " --repo " . escapeshellarg($repo) . " 2>&1");
+            } else {
+                echo "[DRY-RUN] Would commit updates.xml and sync to all branches\n";
             }
         }
 
-        // -- Step 6: Commit updates.xml and sync to all branches --
-        echo "\n--- Step 6: Commit and sync updates.xml ---\n";
-        $root = realpath($path) ?: $path;
-
-        if (!$this->dryRun) {
-            $cdX = PHP_OS_FAMILY === 'Windows' ? "cd /d " : "cd ";
-            $cdRt = $cdX . escapeshellarg($root);
-            $diffCheck = trim((string) @shell_exec(
-                $cdRt . " && git diff --quiet updates.xml"
-                . " 2>&1 && echo clean || echo dirty"
-            ));
-            if ($diffCheck === 'dirty') {
-                @shell_exec($cdRt . " && git add updates.xml");
-                $chMsg = "chore: update channels for"
-                    . " {$releaseVersion} [skip ci]";
-                @shell_exec(
-                    $cdRt . " && git commit -m "
-                    . escapeshellarg($chMsg)
-                    . " --author=\"gitea-actions[bot]"
-                    . " <gitea-actions[bot]@mokoconsulting.tech>\""
-                );
-                @shell_exec(
-                    $cdRt . " && git push origin "
-                    . escapeshellarg($branch) . " 2>&1"
-                );
-                echo "  Committed updates.xml\n";
-            }
-
-            // Sync to all branches
-            passthru("{$php} {$cli}/updates_xml_sync.php --path " . escapeshellarg($path)
-                . " --current " . escapeshellarg($branch) . " --all"
-                . " --version " . escapeshellarg($releaseVersion)
-                . " --token " . escapeshellarg($token)
-                . " --gitea-url " . escapeshellarg($giteaUrl)
-                . " --org " . escapeshellarg($org)
-                . " --repo " . escapeshellarg($repo) . " 2>&1");
-        } else {
-            echo "[DRY-RUN] Would commit updates.xml and sync to all branches\n";
-        }
-
         echo "\n=== Release published: {$releaseVersion} ===\n";
 
         // Output for CI

cli/version_auto_bump.php

@@ -109,18 +109,10 @@ class VersionAutoBumpCli extends CliFramework
             echo "{$line}\n";
         }
 
-        // Step 2: Read version (--quiet suppresses banner so only the version is output)
+        // Step 2: Read version
         $versionOutput = [];
-        exec("{$php} {$cli}/version_read.php --path " . escapeshellarg($path) . " --quiet 2>&1", $versionOutput, $versionRc);
-        // Take the last non-empty line — the version is always the final output
-        $version = '';
-        foreach (array_reverse($versionOutput) as $line) {
-            $line = trim($line);
-            if (preg_match('/^\d{2}\.\d{2}\.\d{2}/', $line)) {
-                $version = $line;
-                break;
-            }
-        }
+        exec("{$php} {$cli}/version_read.php --path " . escapeshellarg($path) . " 2>&1", $versionOutput, $versionRc);
+        $version = trim($versionOutput[0] ?? '');
 
         if (empty($version)) {
             echo "No version found — skipping\n";

cli/version_set_platform.php

@@ -53,12 +53,6 @@ class VersionSetPlatformCli extends CliFramework
         // Strip any existing suffix(es) before applying the correct one
         $version = preg_replace('/(-(dev|alpha|beta|rc))+$/', '', $version);
 
-        // Validate version format — must be XX.YY.ZZ to prevent XML corruption
-        if (!preg_match('/^\d{2}\.\d{2}\.\d{2}$/', $version)) {
-            $this->log('ERROR', "Invalid version format: '{$version}' — expected XX.YY.ZZ");
-            return 1;
-        }
-
         // Append stability suffix for non-stable releases
         $stabilitySuffixMap = [
             'stable'            => '',

lib/Enterprise/CliFramework.php

@@ -141,26 +141,6 @@ abstract class CliFramework
     /** @var float Script start time for elapsed-time reporting. */
     private float $startTime;
 
-    // =========================================================================
-    // Display output — all decorative output goes to stderr
-    // =========================================================================
-
-    /**
-     * Write decorative/diagnostic output to stderr.
-     *
-     * All non-data output (banners, progress bars, section headers, status
-     * lines, log messages) MUST use this method so that stdout is reserved
-     * for machine-readable data.  This ensures that shell captures like
-     *   VERSION=$(php version_read.php --path .)
-     * only receive the actual data, not decorative text.
-     *
-     * @since 04.00.16
-     */
-    protected function display(string $text): void
-    {
-        fwrite(STDERR, $text);
-    }
-
     // =========================================================================
     // Constructor
     // =========================================================================
@@ -346,14 +326,14 @@ abstract class CliFramework
     protected function printHelp(): void
     {
         $w = $this->termWidth();
-        $this->display($this->c(self::C_BOLD . self::C_CYAN, $this->scriptName));
+        echo $this->c(self::C_BOLD . self::C_CYAN, $this->scriptName);
         if ($this->description !== '') {
-            $this->display(' — ' . $this->description);
+            echo ' — ' . $this->description;
         }
-        $this->display("\n");
-        $this->display($this->c(self::C_DIM, str_repeat(self::BOX_H, $w)) . "\n\n");
-        $this->display($this->c(self::C_BOLD, 'Usage:') . "  php {$this->scriptName}.php [options]\n\n");
-        $this->display($this->c(self::C_BOLD, 'Options:') . "\n");
+        echo "\n";
+        echo $this->c(self::C_DIM, str_repeat(self::BOX_H, $w)) . "\n\n";
+        echo $this->c(self::C_BOLD, 'Usage:') . "  php {$this->scriptName}.php [options]\n\n";
+        echo $this->c(self::C_BOLD, 'Options:') . "\n";
 
         $builtIn = [
             '--help'     => ['desc' => 'Show this help message',             'default' => null],
@@ -368,16 +348,16 @@ abstract class CliFramework
             $hint    = ($default !== null && $default !== false)
                 ? $this->c(self::C_DIM, "  (default: {$default})")
                 : '';
-            $this->display(sprintf(
+            printf(
                 "  %s%-22s%s%s%s\n",
                 self::C_CYAN,
                 $name,
                 self::C_RESET,
                 $def['desc'],
                 $hint
-            ));
+            );
         }
-        $this->display("\n");
+        echo "\n";
     }
 
     // =========================================================================
@@ -398,23 +378,23 @@ abstract class CliFramework
         $titleLine   = $this->padRight($titleStyled, $inner, strlen($titleRaw));
         $descLine    = ($desc !== '') ? $this->padRight(" {$desc}", $inner) : null;
 
-        $this->display("\n");
-        $this->display($this->c(
+        echo "\n";
+        echo $this->c(
             self::C_CYAN,
             self::BOX_TL . str_repeat(self::BOX_H, $inner) . self::BOX_TR
-        ) . "\n");
-        $this->display($this->c(self::C_CYAN, self::BOX_V)
+        ) . "\n";
+        echo $this->c(self::C_CYAN, self::BOX_V)
             . $this->c(self::C_BOLD, $titleLine)
-            . $this->c(self::C_CYAN, self::BOX_V) . "\n");
+            . $this->c(self::C_CYAN, self::BOX_V) . "\n";
         if ($descLine !== null) {
-            $this->display($this->c(self::C_CYAN, self::BOX_V)
+            echo $this->c(self::C_CYAN, self::BOX_V)
                 . $this->c(self::C_DIM, $descLine)
-                . $this->c(self::C_CYAN, self::BOX_V) . "\n");
+                . $this->c(self::C_CYAN, self::BOX_V) . "\n";
         }
-        $this->display($this->c(
+        echo $this->c(
             self::C_CYAN,
             self::BOX_BL . str_repeat(self::BOX_H, $inner) . self::BOX_BR
-        ) . "\n\n");
+        ) . "\n\n";
     }
 
     /** Print the dry-run notice box. */
@@ -423,18 +403,18 @@ abstract class CliFramework
         $w   = min($this->termWidth(), 70);
         $msg = '  ' . self::ICON_DRY . '  DRY-RUN MODE — no changes will be written  ';
         $row = $this->padRight($msg, $w - 2);
-        $this->display($this->c(
+        echo $this->c(
             self::C_YELLOW . self::C_BOLD,
             self::BOX_TL . str_repeat(self::BOX_H, $w - 2) . self::BOX_TR
-        ) . "\n");
-        $this->display($this->c(
+        ) . "\n";
+        echo $this->c(
             self::C_YELLOW . self::C_BOLD,
             self::BOX_V . $row . self::BOX_V
-        ) . "\n");
-        $this->display($this->c(
+        ) . "\n";
+        echo $this->c(
             self::C_YELLOW . self::C_BOLD,
             self::BOX_BL . str_repeat(self::BOX_H, $w - 2) . self::BOX_BR
-        ) . "\n\n");
+        ) . "\n\n";
     }
 
     // =========================================================================
@@ -455,11 +435,11 @@ abstract class CliFramework
         $w    = $this->termWidth();
         $text = " {$title} ";
         $fill = max(0, $w - strlen($text) - 4);
-        $this->display("\n");
-        $this->display($this->c(
+        echo "\n";
+        echo $this->c(
             self::C_CYAN,
             str_repeat(self::BOX_H, 2) . $text . str_repeat(self::BOX_H, $fill)
-        ) . "\n\n");
+        ) . "\n\n";
     }
 
     /** Print a plain horizontal divider. */
@@ -469,7 +449,7 @@ abstract class CliFramework
             return;
         }
         $this->clearProgress();
-        $this->display($this->c(self::C_DIM, str_repeat(self::BOX_H, $this->termWidth())) . "\n");
+        echo $this->c(self::C_DIM, str_repeat(self::BOX_H, $this->termWidth())) . "\n";
     }
 
     // =========================================================================
@@ -515,7 +495,11 @@ abstract class CliFramework
 
         $line = "{$ts} {$icon} {$badge} {$text}\n";
 
-        $this->display($line);
+        if ($level === 'ERROR') {
+            fwrite(STDERR, $line);
+        } else {
+            echo $line;
+        }
     }
 
     /** Log a success message. */
@@ -580,7 +564,7 @@ abstract class CliFramework
             ? '  ' . $this->c(self::C_DIM, "— {$detail}")
             : '';
 
-        $this->display('  ' . $this->c($color . self::C_BOLD, $icon) . '  ' . $label . $suffix . "\n");
+        echo '  ' . $this->c($color . self::C_BOLD, $icon) . '  ' . $label . $suffix . "\n";
     }
 
     // =========================================================================
@@ -617,10 +601,10 @@ abstract class CliFramework
         $line = "  [{$bar}] {$percent}  {$counter}{$suffix}";
 
         if ($newline) {
-            $this->display("\r{$line}\n");
+            echo "\r{$line}\n";
             $this->progressActive = false;
         } else {
-            $this->display("\r{$line}");
+            echo "\r{$line}";
             $this->progressActive = true;
         }
     }
@@ -629,7 +613,7 @@ abstract class CliFramework
     protected function clearProgress(): void
     {
         if ($this->progressActive) {
-            $this->display("\r" . str_repeat(' ', $this->termWidth()) . "\r");
+            echo "\r" . str_repeat(' ', $this->termWidth()) . "\r";
             $this->progressActive = false;
         }
     }
@@ -660,8 +644,8 @@ abstract class CliFramework
         $maxKey = max(array_map('strlen', array_keys($rows)));
         $inner  = $maxKey + 20;
 
-        $this->display("\n");
-        $this->display($this->c($color, self::BOX_TL . str_repeat(self::BOX_H, $inner) . self::BOX_TR) . "\n");
+        echo "\n";
+        echo $this->c($color, self::BOX_TL . str_repeat(self::BOX_H, $inner) . self::BOX_TR) . "\n";
 
         foreach ($rows as $label => $value) {
             $valStr    = (string) $value;
@@ -669,10 +653,10 @@ abstract class CliFramework
             $padding   = $inner - strlen($label) - $valVis - 4;
             $row       = '  ' . $this->c(self::C_BOLD, $label)
                 . str_repeat(' ', max(1, $padding)) . $valStr . '  ';
-            $this->display($this->c($color, self::BOX_V) . $row . $this->c($color, self::BOX_V) . "\n");
+            echo $this->c($color, self::BOX_V) . $row . $this->c($color, self::BOX_V) . "\n";
         }
 
-        $this->display($this->c($color, self::BOX_BL . str_repeat(self::BOX_H, $inner) . self::BOX_BR) . "\n\n");
+        echo $this->c($color, self::BOX_BL . str_repeat(self::BOX_H, $inner) . self::BOX_BR) . "\n\n";
     }
 
     /**
@@ -718,7 +702,7 @@ abstract class CliFramework
         $this->clearProgress();
         $badge = $this->c(self::C_BOLD . self::C_MAGENTA, "Step {$current}/{$total}");
         $arrow = $this->c(self::C_DIM, self::ICON_INFO);
-        $this->display("\n{$badge}  {$arrow}  {$title}\n");
+        echo "\n{$badge}  {$arrow}  {$title}\n";
     }
 
     // =========================================================================
@@ -980,13 +964,13 @@ abstract class CliFramework
         }
 
         // Header.
-        $this->display($sep . "\n");
+        echo $sep . "\n";
         $headerLine = '|';
         foreach ($headers as $i => $h) {
             $headerLine .= ' ' . $this->c(self::C_BOLD, str_pad($h, $widths[$i])) . ' |';
         }
-        $this->display($headerLine . "\n");
-        $this->display($sep . "\n");
+        echo $headerLine . "\n";
+        echo $sep . "\n";
 
         // Rows.
         foreach ($rows as $row) {
@@ -994,9 +978,9 @@ abstract class CliFramework
             foreach ($row as $i => $cell) {
                 $line .= ' ' . str_pad((string) $cell, $widths[$i]) . ' |';
             }
-            $this->display($line . "\n");
+            echo $line . "\n";
         }
-        $this->display($sep . "\n");
+        echo $sep . "\n";
     }
 }
 

templates/docs/required/template-update-server-dolibarr.md

@@ -1,56 +1,70 @@
-# Update Server — Dolibarr Modules
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 
-## Overview
+This file is part of a Moko Consulting project.
 
-MokoGitea provides a built-in Update Server that can serve Dolibarr-compatible JSON update feeds from repository releases. **No static feed file is needed in the repository.**
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: {{REPO_NAME}}.Documentation
+INGROUP: MokoPlatform.Templates
+REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}
+PATH: /docs/update-server.md
+VERSION: {{standards_version}}
+BRIEF: How this module's update server file (update.txt) is managed
+-->
+
+# Dolibarr Update Server
+
+[![moko-platform](https://img.shields.io/badge/moko--platform-{{standards_version}}-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform)
+
+This document explains how `update.txt` is automatically managed for this Dolibarr module.
 
 ## How It Works
 
-1. **Enable Update Server** in the repository's Settings > Advanced Settings
-2. **Configure metadata** in Settings > Update Server (set platform to `dolibarr`)
-3. **Create releases** with tagged module archives
-4. MokoGitea serves the update feed at `/{owner}/{repo}/updates/dolibarr.json`
+Dolibarr checks for module updates by fetching a plain-text file from the URL in `$this->url_last_version` in the module descriptor (`src/core/modules/mod*.class.php`). The file must contain **only the version string** — no JSON, no XML, no trailing newline.
 
-## Feed URL
+### Automatic Generation
+
+| Event | Workflow | `update.txt` Content | `$this->version` |
+|-------|----------|---------------------|-------------------|
+| Merge to `main` | `auto-release.yml` | `XX.YY.ZZ` (real version) | Real version |
+| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` |
+| Push to `rc/**` | `deploy-dev.yml` | `XX.YY.ZZ-rc` | RC version |
+
+### Module Descriptor
+
+The `url_last_version` in your module descriptor should point to:
 
 ```
-https://git.mokoconsulting.tech/{owner}/{repo}/updates/dolibarr.json
+https://raw.githubusercontent.com/mokoconsulting-tech/{{REPO_NAME}}/main/update.txt
 ```
 
-## Release Naming Convention
+This is set automatically by `version_set_platform.php` during the build pipeline. **Never manually edit `$this->version` or `$this->url_last_version`** — the workflows handle it.
 
-Release assets should follow:
+### Branch Lifecycle
 
 ```
-{module_name}-{version}.zip
+dev/XX.YY.ZZ  →  rc/XX.YY.ZZ  →  main  →  version/XX
+(development)     (release candidate)  (stable release)  (frozen snapshot)
 ```
 
-Examples:
-- `mokocrm-18.0.1.zip`
-- `mokodolisign-3.2.0.zip`
+1. **Development** (`dev/**`): `update.txt` = `development`, `$this->version` = `development`
+2. **Release Candidate** (`rc/**`): `update.txt` = `XX.YY.ZZ-rc`, version set to RC
+3. **Stable Release** (merge to `main`): `auto-release.yml` writes real version to `update.txt`, creates GitHub Release + tag, creates `version/XX` branch
+4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed
 
-## Update Server Settings
+### Health Checks
 
-Configure these in Settings > Update Server:
+The `repo_health.yml` workflow verifies on every commit:
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| Platform | Set to `dolibarr` | `dolibarr` |
-| Extension Name | Dolibarr module directory name | `mokocrm` |
-| Display Name | Human-readable name | `Module - MokoCRM` |
-| Extension Type | Usually `module` | `module` |
-| Maintainer | Organization name | `Moko Consulting` |
-| Support URL | Product support page | `https://mokoconsulting.tech/support/mokocrm` |
+- `update.txt` exists in the repository root
+- Module descriptor (`mod*.class.php`) exists in `src/core/modules/`
+- `$this->numero` is set and non-zero
+- `$this->version` is not hardcoded (should be set by workflow)
+- `url_last_version` points to `update.txt` (not `update.json`)
+- `url_last_version` references `/main/` branch on the main branch
 
-## Download Gating
+---
 
-Same three modes as Joomla: `none`, `prerelease`, `all`.
-
-## Status
-
-Dolibarr Update Server support is currently **disabled for all modules except MokoCRM**. Metadata is pre-configured and ready to enable when needed.
-
-## What NOT to Do
-
-- **Do NOT commit static feed files to the repository**
-- **Do NOT use legacy update check mechanisms** — use the built-in feed
+*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.*

templates/docs/required/template-update-server-joomla.md

@@ -1,90 +1,122 @@
-# Update Server — Joomla Extensions
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 
-## Overview
+This file is part of a Moko Consulting project.
 
-MokoGitea provides a built-in Update Server that dynamically generates Joomla-compatible update XML feeds from repository releases. **No static `updates.xml` file is needed in the repository.**
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: {{REPO_NAME}}.Documentation
+INGROUP: MokoPlatform.Templates
+REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}
+PATH: /docs/update-server.md
+VERSION: {{standards_version}}
+BRIEF: How this extension's Joomla update server file (updates.xml) is managed
+-->
+
+# Joomla Update Server
+
+[![moko-platform](https://img.shields.io/badge/moko--platform-{{standards_version}}-blue)](https://git.mokoconsulting.tech/MokoConsulting/moko-platform)
+
+This document explains how `updates.xml` is automatically managed for this Joomla extension following the [Joomla Update Server specification](https://docs.joomla.org/Deploying_an_Update_Server).
 
 ## How It Works
 
-1. **Enable Update Server** in the repository's Settings > Advanced Settings
-2. **Configure metadata** in Settings > Update Server (extension name, type, target version, etc.)
-3. **Create releases** with tagged assets (e.g. `pkg_mokowaas-02.19.00.zip`)
-4. MokoGitea automatically serves the update feed at `/{owner}/{repo}/updates.xml`
+Joomla checks for extension updates by fetching an XML file from the URL defined in the `<updateservers>` tag in the extension's XML manifest. moko-platform generates this file automatically.
 
-## Feed URL
+### Automatic Generation
 
-```
-https://git.mokoconsulting.tech/{owner}/{repo}/updates.xml
-```
+| Event | Workflow | `<tag>` | `<version>` |
+|-------|----------|---------|-------------|
+| Merge to `main` | `auto-release.yml` | `stable` | `XX.YY.ZZ` |
+| Push to `dev/**` | `deploy-dev.yml` | `development` | `development` |
+| Push to `rc/**` | `deploy-dev.yml` | `rc` | `XX.YY.ZZ-rc` |
 
-This URL is what goes into your Joomla extension's `update_server` element in the manifest XML.
-
-## Manifest Configuration
-
-In your extension's manifest XML (`*.xml`), add:
+### Generated XML Structure
 
 ```xml
-<updateservers>
-  <server type="extension" name="{Extension Name}">
-    https://git.mokoconsulting.tech/MokoConsulting/{RepoName}/updates.xml
-  </server>
-</updateservers>
+<?xml version="1.0" encoding="utf-8"?>
+<updates>
+    <update>
+        <name>Extension Name</name>
+        <description>Extension Name update</description>
+        <element>com_extensionname</element>
+        <type>component</type>
+        <version>01.02.03</version>
+        <client>site</client>
+        <folder>system</folder>          <!-- plugins only -->
+        <tags>
+            <tag>stable</tag>
+        </tags>
+        <downloads>
+            <downloadurl type="full" format="zip">https://git.mokoconsulting.tech/.../releases/download/v01.02.03/com_ext-01.02.03.zip</downloadurl>
+            <downloadurl type="full" format="zip">https://github.com/.../releases/download/v01.02.03/com_ext-01.02.03.zip</downloadurl>
+        </downloads>
+        <targetplatform name="joomla" version="((5\.[0-9])|(6\.[0-9]))" />
+        <php_minimum>8.2</php_minimum>   <!-- if present in manifest -->
+        <maintainer>Moko Consulting</maintainer>
+        <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    </update>
+</updates>
 ```
 
-## Release Naming Convention
+### Metadata Source
 
-Release assets must follow this naming pattern for the feed generator to detect them:
+All metadata is extracted from the extension's XML manifest (`src/*.xml`) at build time:
 
-```
-{extension_name}-{version}.zip
-{extension_name}-{version}.tar.gz
+| XML Element | Source | Notes |
+|-------------|--------|-------|
+| `<name>` | `<name>` in manifest | Extension display name |
+| `<element>` | `<element>` in manifest | Must match installed extension identifier |
+| `<type>` | `type` attribute on `<extension>` | `component`, `module`, `plugin`, `library`, `package`, `template` |
+| `<client>` | `client` attribute on `<extension>` | `site` or `administrator` — **required for plugins and modules** |
+| `<folder>` | `group` attribute on `<extension>` | Plugin group (e.g., `system`, `content`) — **required for plugins** |
+| `<targetplatform>` | `<targetplatform>` in manifest | Falls back to Joomla 5.x / 6.x if not specified |
+| `<php_minimum>` | `<php_minimum>` in manifest | Included only if present |
+
+### Extension Manifest Setup
+
+Your XML manifest must include an `<updateservers>` tag pointing to the `updates.xml` on the `main` branch:
+
+```xml
+<extension type="component" client="site" method="upgrade">
+    <name>My Extension</name>
+    <element>com_myextension</element>
+    <!-- ... -->
+    <updateservers>
+        <server type="extension" priority="1" name="My Extension Update Server (Gitea)">
+            https://git.mokoconsulting.tech/mokoconsulting-tech/{{REPO_NAME}}/raw/branch/main/updates.xml
+        </server>
+        <server type="extension" priority="2" name="My Extension Update Server (GitHub)">
+            https://raw.githubusercontent.com/mokoconsulting-tech/{{REPO_NAME}}/main/updates.xml
+        </server>
+    </updateservers>
+</extension>
 ```
 
-Examples:
-- `pkg_mokowaas-02.19.00.zip`
-- `tpl_mokoonyx-02.19.00.zip`
-- `mod_mokojoomhero-01.05.00.zip`
-
-## Update Server Settings
-
-Configure these in Settings > Update Server:
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| Extension Name | Joomla element name | `pkg_mokowaas` |
-| Display Name | Human-readable name | `Package - MokoWaaS` |
-| Extension Type | package, plugin, template, module, component | `package` |
-| Target Version | Regex for compatible Joomla versions | `(5|6)\..*` |
-| PHP Minimum | Minimum PHP version | `8.1` |
-| Maintainer | Organization name | `Moko Consulting` |
-| Maintainer URL | Organization website | `https://mokoconsulting.tech` |
-| Support URL | Product support page | `https://mokoconsulting.tech/products/{alias}` |
-| Info URL | Product information page | `https://mokoconsulting.tech/products/{alias}` |
-
-## Download Gating
-
-Three modes control who can download release assets:
-
-| Mode | Behavior |
-|------|----------|
-| `none` | All downloads are public |
-| `prerelease` | Pre-release downloads require a license key; stable releases are public |
-| `all` | All downloads require a license key |
-
-The update feed XML is **always public** — only the actual file downloads are gated.
-
-## What NOT to Do
-
-- **Do NOT commit `updates.xml` to the repository** — it is served dynamically
-- **Do NOT use static update server workflows** — the old CI-generated approach is deprecated
-- **Do NOT hardcode version numbers in feed URLs** — the feed auto-detects from releases
-
-## Changelog Feed
-
-A changelog XML is also served automatically at:
+### Branch Lifecycle
 
 ```
-https://git.mokoconsulting.tech/{owner}/{repo}/changelog.xml
+dev/XX.YY.ZZ  →  rc/XX.YY.ZZ  →  main  →  version/XX
+(development)     (rc)              (stable)    (frozen snapshot)
 ```
 
-This is generated from release notes (markdown body of each release).
+1. **Development** (`dev/**`): `updates.xml` with `<tag>development</tag>`, download points to branch archive
+2. **Release Candidate** (`rc/**`): `updates.xml` with `<tag>rc</tag>`, version set to `XX.YY.ZZ-rc`
+3. **Stable Release** (merge to `main`): `updates.xml` with `<tag>stable</tag>`, download points to Gitea Release asset (primary) + GitHub Release asset (mirror)
+4. **Frozen Snapshot** (`version/XX`): immutable, never force-pushed
+
+### Health Checks
+
+The `repo_health.yml` workflow verifies on every commit:
+
+- `updates.xml` exists in the repository root
+- XML manifest exists with `<extension>` tag
+- `<version>`, `<name>`, `<author>`, `<namespace>` tags present
+- Extension `type` attribute is valid
+- Language `.ini` files exist
+- `index.html` directory listing protection in `src/`, `src/admin/`, `src/site/`
+
+---
+
+*Managed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform). See [docs/workflows/update-server.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/workflows/update-server.md) for the full specification.*

templates/joomla/updates.xml.template

@@ -0,0 +1,119 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ SPDX-License-Identifier: GPL-3.0-or-later
+ VERSION: {{VERSION}}
+ -->
+
+<updates>
+
+  <!-- 1. DEVELOPMENT -->
+  <update>
+    <name>{{EXTENSION_NAME}}</name>
+    <description>{{EXTENSION_NAME}} development build — unstable.</description>
+    <element>{{EXTENSION_ELEMENT}}</element>
+    <type>{{EXTENSION_TYPE}}</type>
+    <folder>{{EXTENSION_FOLDER}}</folder>
+    <client>{{EXTENSION_CLIENT}}</client>
+    <version>{{VERSION}}</version>
+    <creationDate>{{DATE}}</creationDate>
+    <infourl title='{{EXTENSION_NAME}} Dev'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/development</infourl>
+    <downloads>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/development/{{EXTENSION_ELEMENT}}-{{VERSION}}-dev.zip</downloadurl>
+    </downloads>
+    <sha256></sha256>
+    <tags><tag>development</tag></tags>
+    <maintainer>Moko Consulting</maintainer>
+    <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    <targetplatform name='joomla' version='(5|6).*'/>
+    <php_minimum>8.1</php_minimum>
+  </update>
+
+  <!-- 2. ALPHA -->
+  <update>
+    <name>{{EXTENSION_NAME}}</name>
+    <description>{{EXTENSION_NAME}} alpha build — early testing.</description>
+    <element>{{EXTENSION_ELEMENT}}</element>
+    <type>{{EXTENSION_TYPE}}</type>
+    <folder>{{EXTENSION_FOLDER}}</folder>
+    <client>{{EXTENSION_CLIENT}}</client>
+    <version>{{VERSION}}</version>
+    <creationDate>{{DATE}}</creationDate>
+    <infourl title='{{EXTENSION_NAME}} Alpha'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/alpha</infourl>
+    <downloads>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/alpha/{{EXTENSION_ELEMENT}}-{{VERSION}}-alpha.zip</downloadurl>
+    </downloads>
+    <sha256></sha256>
+    <tags><tag>alpha</tag></tags>
+    <maintainer>Moko Consulting</maintainer>
+    <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    <targetplatform name='joomla' version='(5|6).*'/>
+    <php_minimum>8.1</php_minimum>
+  </update>
+
+  <!-- 3. BETA -->
+  <update>
+    <name>{{EXTENSION_NAME}}</name>
+    <description>{{EXTENSION_NAME}} beta build — feature complete, stability testing.</description>
+    <element>{{EXTENSION_ELEMENT}}</element>
+    <type>{{EXTENSION_TYPE}}</type>
+    <folder>{{EXTENSION_FOLDER}}</folder>
+    <client>{{EXTENSION_CLIENT}}</client>
+    <version>{{VERSION}}</version>
+    <creationDate>{{DATE}}</creationDate>
+    <infourl title='{{EXTENSION_NAME}} Beta'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/beta</infourl>
+    <downloads>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/beta/{{EXTENSION_ELEMENT}}-{{VERSION}}-beta.zip</downloadurl>
+    </downloads>
+    <sha256></sha256>
+    <tags><tag>beta</tag></tags>
+    <maintainer>Moko Consulting</maintainer>
+    <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    <targetplatform name='joomla' version='(5|6).*'/>
+    <php_minimum>8.1</php_minimum>
+  </update>
+
+  <!-- 4. RC -->
+  <update>
+    <name>{{EXTENSION_NAME}}</name>
+    <description>{{EXTENSION_NAME}} release candidate — testing only.</description>
+    <element>{{EXTENSION_ELEMENT}}</element>
+    <type>{{EXTENSION_TYPE}}</type>
+    <folder>{{EXTENSION_FOLDER}}</folder>
+    <client>{{EXTENSION_CLIENT}}</client>
+    <version>{{VERSION}}</version>
+    <creationDate>{{DATE}}</creationDate>
+    <infourl title='{{EXTENSION_NAME}} RC'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/release-candidate</infourl>
+    <downloads>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/release-candidate/{{EXTENSION_ELEMENT}}-{{VERSION}}-rc.zip</downloadurl>
+    </downloads>
+    <sha256></sha256>
+    <tags><tag>rc</tag></tags>
+    <maintainer>Moko Consulting</maintainer>
+    <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    <targetplatform name='joomla' version='(5|6).*'/>
+    <php_minimum>8.1</php_minimum>
+  </update>
+
+  <!-- 5. STABLE -->
+  <update>
+    <name>{{EXTENSION_NAME}}</name>
+    <description>{{EXTENSION_NAME}} — Moko Consulting Joomla extension.</description>
+    <element>{{EXTENSION_ELEMENT}}</element>
+    <type>{{EXTENSION_TYPE}}</type>
+    <folder>{{EXTENSION_FOLDER}}</folder>
+    <client>{{EXTENSION_CLIENT}}</client>
+    <version>{{VERSION}}</version>
+    <creationDate>{{DATE}}</creationDate>
+    <infourl title='{{EXTENSION_NAME}}'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/tag/stable</infourl>
+    <downloads>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/releases/download/stable/{{EXTENSION_ELEMENT}}-{{VERSION}}.zip</downloadurl>
+    </downloads>
+    <sha256></sha256>
+    <tags><tag>stable</tag></tags>
+    <maintainer>Moko Consulting</maintainer>
+    <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    <targetplatform name='joomla' version='(5|6).*'/>
+    <php_minimum>8.1</php_minimum>
+  </update>
+
+</updates>