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

Authored-by: Moko Consulting

.mokogitea/branch-protection.yml

@@ -0,0 +1,251 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+# SPDX-License-Identifier: GPL-3.0-or-later
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Automation
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /.gitea/workflows/branch-protection.yml
+# BRIEF: Apply standardised branch protection rules to all governed repositories
+#
+# +========================================================================+
+# |                   BRANCH PROTECTION SETUP                              |
+# +========================================================================+
+# |                                                                        |
+# |  Applies protection rules for: main, dev, rc, beta, alpha       |
+# |                                                                        |
+# |  main  — Require PR, block rejected reviews, no force push             |
+# |  dev   — Allow push, no force push, no delete                          |
+# |  rc  — Allow push, no force push, no delete                          |
+# |  beta — Allow push, no force push, no delete                         |
+# |  alpha — Allow push, no force push, no delete                        |
+# |                                                                        |
+# |  jmiller has override authority on all branches.                       |
+# |                                                                        |
+# +========================================================================+
+
+name: Branch Protection Setup
+
+on:
+  schedule:
+    - cron: '0 2 * * 1'  # Weekly Monday 02:00 UTC
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Preview mode (no changes)'
+        required: false
+        type: boolean
+        default: false
+      repos:
+        description: 'Comma-separated repo names (empty = all governed repos)'
+        required: false
+        type: string
+        default: ''
+
+env:
+  GITEA_URL: https://git.mokoconsulting.tech
+  GITEA_ORG: MokoConsulting
+
+permissions:
+  contents: read
+
+jobs:
+  protect:
+    name: Apply Branch Protection Rules
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Determine target repos
+        id: repos
+        env:
+          GA_TOKEN: ${{ secrets.GA_TOKEN }}
+        run: |
+          API="${GITEA_URL}/api/v1"
+
+          # Platform/standards/infra repos to exclude
+          EXCLUDE="gitea-org-config org-profile gitea-private .mokogitea-private MokoStandards moko-platform MokoTesting"
+          EXCLUDE="$EXCLUDE MokoStandards-Template-Client MokoStandards-Template-Dolibarr MokoStandards-Template-Generic MokoStandards-Template-Joomla MokoDoliProjTemplate"
+
+          if [ -n "${{ inputs.repos }}" ]; then
+            # User-specified repos
+            REPOS=$(echo "${{ inputs.repos }}" | tr ',' ' ')
+          else
+            # Fetch all org repos
+            PAGE=1
+            REPOS=""
+            while true; do
+              BATCH=$(curl -sS \
+                -H "Authorization: token ${GA_TOKEN}" \
+                "${API}/orgs/${GITEA_ORG}/repos?page=${PAGE}&limit=50" \
+                | jq -r '.[].name // empty')
+              [ -z "$BATCH" ] && break
+              REPOS="$REPOS $BATCH"
+              PAGE=$((PAGE + 1))
+            done
+
+            # Filter out excluded repos
+            FILTERED=""
+            for REPO in $REPOS; do
+              SKIP=false
+              for EX in $EXCLUDE; do
+                if [ "$REPO" = "$EX" ]; then
+                  SKIP=true
+                  break
+                fi
+              done
+              if [ "$SKIP" = "false" ]; then
+                FILTERED="$FILTERED $REPO"
+              fi
+            done
+            REPOS="$FILTERED"
+          fi
+
+          echo "repos=$REPOS" >> "$GITHUB_OUTPUT"
+          COUNT=$(echo "$REPOS" | wc -w)
+          echo "📋 Target repos (${COUNT}): $REPOS"
+
+      - name: Apply protection rules
+        env:
+          GA_TOKEN: ${{ secrets.GA_TOKEN }}
+          DRY_RUN: ${{ inputs.dry_run || 'false' }}
+        run: |
+          API="${GITEA_URL}/api/v1"
+          REPOS="${{ steps.repos.outputs.repos }}"
+
+          SUCCESS=0
+          FAILED=0
+          SKIPPED=0
+
+          # ── Rule definitions ──────────────────────────────────────
+          # Only the CI bot (jmiller token) can push directly.
+          # All human contributors must use PRs.
+          # Force push disabled on all branches.
+
+          RULE_MAIN='{
+            "rule_name": "main",
+            "enable_push": true,
+            "enable_push_whitelist": true,
+            "push_whitelist_usernames": ["jmiller"],
+            "enable_force_push": false,
+            "enable_force_push_allowlist": false,
+            "force_push_allowlist_usernames": [],
+            "enable_merge_whitelist": false,
+            "required_approvals": 0,
+            "dismiss_stale_approvals": true,
+            "block_on_rejected_reviews": true,
+            "block_on_outdated_branch": false,
+            "priority": 1
+          }'
+
+          RULE_DEV='{
+            "rule_name": "dev",
+            "enable_push": true,
+            "enable_push_whitelist": true,
+            "push_whitelist_usernames": ["jmiller"],
+            "enable_force_push": false,
+            "enable_force_push_allowlist": false,
+            "force_push_allowlist_usernames": [],
+            "enable_merge_whitelist": false,
+            "required_approvals": 0,
+            "block_on_rejected_reviews": false,
+            "priority": 2
+          }'
+
+          RULE_RC='{
+            "rule_name": "rc",
+            "enable_push": true,
+            "enable_push_whitelist": true,
+            "push_whitelist_usernames": ["jmiller"],
+            "enable_force_push": false,
+            "enable_force_push_allowlist": false,
+            "force_push_allowlist_usernames": [],
+            "enable_merge_whitelist": false,
+            "required_approvals": 0,
+            "block_on_rejected_reviews": false,
+            "priority": 3
+          }'
+
+          RULE_BETA='{
+            "rule_name": "beta",
+            "enable_push": true,
+            "enable_push_whitelist": true,
+            "push_whitelist_usernames": ["jmiller"],
+            "enable_force_push": false,
+            "enable_force_push_allowlist": false,
+            "force_push_allowlist_usernames": [],
+            "enable_merge_whitelist": false,
+            "required_approvals": 0,
+            "block_on_rejected_reviews": false,
+            "priority": 4
+          }'
+
+          RULE_ALPHA='{
+            "rule_name": "alpha",
+            "enable_push": true,
+            "enable_push_whitelist": true,
+            "push_whitelist_usernames": ["jmiller"],
+            "enable_force_push": false,
+            "enable_force_push_allowlist": false,
+            "force_push_allowlist_usernames": [],
+            "enable_merge_whitelist": false,
+            "required_approvals": 0,
+            "block_on_rejected_reviews": false,
+            "priority": 5
+          }'
+
+          RULES=("$RULE_MAIN" "$RULE_DEV" "$RULE_RC" "$RULE_BETA" "$RULE_ALPHA")
+          RULE_NAMES=("main" "dev" "rc" "beta" "alpha")
+
+          # ── Apply rules to each repo ──────────────────────────────
+          for REPO in $REPOS; do
+            echo ""
+            echo "═══ ${REPO} ═══"
+
+            for i in "${!RULES[@]}"; do
+              RULE="${RULES[$i]}"
+              NAME="${RULE_NAMES[$i]}"
+
+              if [ "$DRY_RUN" = "true" ]; then
+                echo "  [DRY RUN] Would apply rule: ${NAME}"
+                SKIPPED=$((SKIPPED + 1))
+                continue
+              fi
+
+              # Delete existing rule if present (idempotent recreate)
+              ENCODED_NAME=$(echo "$NAME" | sed 's|/|%2F|g')
+              curl -sS -o /dev/null -w "" \
+                -X DELETE \
+                -H "Authorization: token ${GA_TOKEN}" \
+                "${API}/repos/${GITEA_ORG}/${REPO}/branch_protections/${ENCODED_NAME}" 2>/dev/null || true
+
+              # Create rule
+              RESPONSE=$(curl -sS -w "\n%{http_code}" \
+                -X POST \
+                -H "Authorization: token ${GA_TOKEN}" \
+                -H "Content-Type: application/json" \
+                -d "$RULE" \
+                "${API}/repos/${GITEA_ORG}/${REPO}/branch_protections")
+
+              HTTP=$(echo "$RESPONSE" | tail -1)
+              BODY=$(echo "$RESPONSE" | sed '$d')
+
+              if [ "$HTTP" = "201" ]; then
+                echo "  ✅ ${NAME}"
+                SUCCESS=$((SUCCESS + 1))
+              else
+                echo "  ❌ ${NAME} (HTTP ${HTTP}): $(echo "$BODY" | jq -r '.message // .' 2>/dev/null | head -1)"
+                FAILED=$((FAILED + 1))
+              fi
+            done
+          done
+
+          # ── Summary ───────────────────────────────────────────────
+          echo ""
+          echo "════════════════════════════════════════"
+          echo "  ✅ Success: ${SUCCESS}"
+          echo "  ❌ Failed:  ${FAILED}"
+          echo "  ⏭️  Skipped: ${SKIPPED}"
+          echo "════════════════════════════════════════"
+
+          if [ "$FAILED" -gt 0 ]; then
+            echo "::warning::${FAILED} rule(s) failed to apply"
+          fi

.mokogitea/workflows/auto-bump.yml

@@ -0,0 +1,66 @@
+# 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: /.mokogitea/workflows/auto-bump.yml
+# VERSION: 09.02.00
+# BRIEF: Auto patch-bump version on every push to dev (skips merge commits)
+
+name: "Universal: Auto Version Bump"
+
+on:
+  push:
+    branches:
+      - dev
+      - rc
+      - 'feature/**'
+      - 'patch/**'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    name: Version Bump
+    runs-on: release
+    if: >-
+      !contains(github.event.head_commit.message, '[skip ci]') &&
+      !contains(github.event.head_commit.message, '[skip bump]') &&
+      !startsWith(github.event.head_commit.message, 'Merge pull request')
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 1
+
+      - name: Setup moko-platform tools
+        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 "/opt/moko-platform/cli" ]; then
+            echo "MOKO_CLI=/opt/moko-platform/cli" >> "$GITHUB_ENV"
+          else
+            git clone --depth 1 --branch main --quiet \
+              "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/MokoConsulting/moko-platform.git" \
+              /tmp/moko-platform-api
+            cd /tmp/moko-platform-api && composer install --no-dev --no-interaction --quiet
+            echo "MOKO_CLI=/tmp/moko-platform-api/cli" >> "$GITHUB_ENV"
+          fi
+
+      - name: Bump version
+        run: |
+          php ${MOKO_CLI}/version_auto_bump.php \
+            --path . --branch "${GITHUB_REF_NAME}" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
+            --repo-url "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"

.mokogitea/workflows/auto-release.yml

@@ -0,0 +1,270 @@
+# 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-tech/moko-platform
+# PATH: /templates/workflows/universal/auto-release.yml.template
+# VERSION: 05.00.00
+# BRIEF: Universal build & release � detects platform from manifest.xml
+#
+# +========================================================================+
+# |              UNIVERSAL BUILD & RELEASE PIPELINE                        |
+# +========================================================================+
+# |                                                                        |
+# |  Reads manifest.xml (joomla|dolibarr|generic) to branch logic.       |
+# |                                                                        |
+# |  Platform-specific:                                                    |
+# |    joomla:   XML manifest, updates.xml, type-prefixed packages         |
+# |    dolibarr: mod*.class.php, update.txt, dev version reset             |
+# |    generic:  README-only, no update stream                             |
+# |                                                                        |
+# +========================================================================+
+
+name: "Universal: Build & Release"
+
+on:
+  pull_request:
+    types: [opened, closed]
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      action:
+        description: 'Action to perform'
+        required: false
+        type: choice
+        default: release
+        options:
+          - release
+          - promote-rc
+
+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:
+  # ── PR Opened → Rename branch to RC and build RC release ─────────────────────
+  promote-rc:
+    name: Promote to RC
+    runs-on: release
+    if: >-
+      (github.event.action == 'opened' && github.event.pull_request.merged != true) ||
+      (github.event_name == 'workflow_dispatch' && inputs.action == 'promote-rc')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 1
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+        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
+          # 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" \
+            /tmp/moko-platform-api
+          cd /tmp/moko-platform-api
+          composer install --no-dev --no-interaction --quiet
+
+      - name: Rename branch to rc
+        run: |
+          php /tmp/moko-platform-api/cli/branch_rename.php \
+            --from "${{ github.event.pull_request.head.ref || 'dev' }}" --to rc \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
+            --api-base "${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}" \
+            --pr "${{ github.event.pull_request.number }}"
+
+      - name: Checkout rc and configure git
+        run: |
+          git fetch origin rc
+          git checkout rc
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Publish RC release
+        run: |
+          php /tmp/moko-platform-api/cli/release_publish.php \
+            --path . --stability rc --bump minor --branch rc \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}"
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Promoted to Release Candidate" >> $GITHUB_STEP_SUMMARY
+          echo "Branch renamed to rc, minor bump, RC + lesser stream releases built, updates.xml synced" >> $GITHUB_STEP_SUMMARY
+
+  # ── Merged PR → Build & Release (or promote RC to stable) ────────────────────
+  release:
+    name: Build & Release Pipeline
+    runs-on: release
+    if: >-
+      github.event.pull_request.merged == true ||
+      (github.event_name == 'workflow_dispatch' && inputs.action != 'promote-rc')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 0
+
+      - name: Configure git for bot pushes
+        run: |
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GH_MIRROR_TOKEN }}"}}'
+        run: |
+          # Ensure PHP + Composer are available
+          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
+          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" \
+            /tmp/moko-platform-api
+          cd /tmp/moko-platform-api
+          composer install --no-dev --no-interaction --quiet
+
+
+      - name: "Publish stable release"
+        run: |
+          php /tmp/moko-platform-api/cli/release_publish.php \
+            --path . --stability stable --bump minor --branch main \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}"
+
+      # -- STEP 9: Mirror to GitHub (stable only) --------------------------------
+      - name: "Step 9: Mirror release to GitHub"
+        if: >-
+          steps.version.outputs.skip != 'true' &&
+          secrets.GH_MIRROR_TOKEN != ''
+        continue-on-error: true
+        run: |
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
+          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php /tmp/moko-platform-api/cli/release_mirror.php \
+            --version "$VERSION" --tag "$RELEASE_TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --gh-token "${{ secrets.GH_MIRROR_TOKEN }}" --gh-repo "$GH_REPO" \
+            --branch main 2>&1 || true
+          echo "GitHub mirror updated" >> $GITHUB_STEP_SUMMARY
+
+      # -- STEP 10: Sync main branch to GitHub mirror ----------------------------
+      - name: "Step 10: Push main to GitHub mirror"
+        if: >-
+          steps.version.outputs.skip != 'true' &&
+          secrets.GH_MIRROR_TOKEN != ''
+        continue-on-error: true
+        run: |
+          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
+          GH_ORG=$(echo "$GH_REPO" | cut -d/ -f1)
+          GH_NAME=$(echo "$GH_REPO" | cut -d/ -f2)
+          git remote add github "https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git" 2>/dev/null || \
+            git remote set-url github "https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git"
+          git fetch origin main --depth=1
+          git push github origin/main:refs/heads/main --force 2>/dev/null \
+            && echo "main branch pushed to GitHub mirror" \
+            || echo "WARNING: GitHub mirror push failed"
+
+      - name: "Step 11: Delete rc branch and recreate dev from main"
+        if: steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
+
+          # Delete rc branch (ephemeral — created by promote-rc)
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/branches/rc" 2>/dev/null \
+            && echo "Deleted rc branch" || echo "rc branch not found"
+
+          # Delete dev branch
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/branches/dev" 2>/dev/null && echo "Deleted dev branch"
+
+          # Recreate dev from main (now includes version bump + changelog promotion)
+          curl -sf -X POST -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${API_BASE}/branches" \
+            -d '{"new_branch_name":"dev","old_branch_name":"main"}' 2>/dev/null && echo "Recreated dev from main"
+
+          echo "Pre-release branches cleaned, dev reset from main" >> $GITHUB_STEP_SUMMARY
+
+      - name: "Step 12: Create version branch from main"
+        if: steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          BRANCH_NAME="version/${VERSION}"
+          MAIN_SHA=$(git rev-parse HEAD)
+
+          # Delete old version branch if it exists (same version re-release)
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}"             "${API_BASE}/branches/${BRANCH_NAME}" 2>/dev/null && echo "Deleted old ${BRANCH_NAME}"
+
+          # Create version/XX.YY.ZZ from main
+          curl -sf -X POST -H "Authorization: token ${TOKEN}"             -H "Content-Type: application/json"             "${API_BASE}/branches"             -d "{\"new_branch_name\":\"${BRANCH_NAME}\",\"old_branch_name\":\"main\"}" 2>/dev/null             && echo "Created ${BRANCH_NAME} from main (${MAIN_SHA})"             || echo "WARNING: ${BRANCH_NAME} creation failed"
+
+          echo "Version branch created: ${BRANCH_NAME} (${MAIN_SHA})" >> $GITHUB_STEP_SUMMARY
+
+
+
+      # -- Dolibarr post-release: Reset dev version -----------------------------
+      - name: "Post-release: Reset dev version"
+        if: steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php /tmp/moko-platform-api/cli/version_reset_dev.php \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "${API_BASE}" \
+            --branch dev --path . 2>&1 || true
+
+      # -- Summary --------------------------------------------------------------
+      - name: Pipeline Summary
+        if: always()
+        run: |
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          if [ "${{ steps.version.outputs.skip }}" = "true" ]; then
+            echo "## Release Skipped" >> $GITHUB_STEP_SUMMARY
+            echo "No VERSION in README.md" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ steps.check.outputs.already_released }}" = "true" ]; then
+            echo "## Already Released — ${VERSION}" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "## Build & Release Complete (${PLATFORM})" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "| Step | Result |" >> $GITHUB_STEP_SUMMARY
+            echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
+            echo "| Platform | \`${PLATFORM}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Branch | \`${{ steps.version.outputs.branch }}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Tag | \`${{ steps.version.outputs.tag }}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Release | [View](${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/tag/${{ steps.version.outputs.tag }}) |" >> $GITHUB_STEP_SUMMARY
+          fi

.mokogitea/workflows/branch-cleanup.yml

@@ -0,0 +1,48 @@
+# 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: /.mokogitea/workflows/branch-cleanup.yml
+# VERSION: 01.00.00
+# BRIEF: Delete feature branches after PR merge
+
+name: "Branch Cleanup"
+
+on:
+  pull_request:
+    types: [closed]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  cleanup:
+    name: Delete merged branch
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.head.ref != 'dev' &&
+      github.event.pull_request.head.ref != 'main'
+
+    steps:
+      - name: Delete source branch
+        run: |
+          BRANCH="${{ github.event.pull_request.head.ref }}"
+          API="${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}/api/v1/repos/${{ github.repository }}/branches"
+          ENCODED=$(php -r "echo rawurlencode('${BRANCH}');")
+
+          STATUS=$(curl -sf -o /dev/null -w "%{http_code}" -X DELETE \
+            -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \
+            "${API}/${ENCODED}" 2>/dev/null || true)
+
+          if [ "$STATUS" = "204" ]; then
+            echo "Deleted branch: ${BRANCH}" >> $GITHUB_STEP_SUMMARY
+          elif [ "$STATUS" = "404" ]; then
+            echo "Branch already deleted: ${BRANCH}" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "::warning::Failed to delete branch ${BRANCH} (HTTP ${STATUS})"
+          fi

.mokogitea/workflows/cascade-dev.yml

@@ -0,0 +1,10 @@
+# DISABLED — auto-release Step 11 recreates dev from main after every release.
+# Cascade-dev is redundant and causes version conflicts when both main and dev
+# have different version numbers in templateDetails.xml / manifest.xml.
+name: "Cascade Main → Dev (DISABLED)"
+on: workflow_dispatch
+jobs:
+  noop:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Cascade disabled — auto-release handles dev recreation"

.mokogitea/workflows/issue-branch.yml

@@ -0,0 +1,73 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Automation
+# VERSION: 01.00.00
+# BRIEF: Auto-create feature branch when an issue is opened
+
+name: "Universal: Issue Branch"
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: write
+  issues: write
+
+env:
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+
+jobs:
+  create-branch:
+    name: Create feature branch
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create branch and comment
+        run: |
+          TOKEN="${{ secrets.GA_TOKEN }}"
+          API="${GITEA_URL}/api/v1/repos/${{ github.repository }}"
+          ISSUE_NUM="${{ github.event.issue.number }}"
+          ISSUE_TITLE="${{ github.event.issue.title }}"
+
+          # Build slug from title: lowercase, replace non-alnum with dash, trim
+          SLUG=$(echo "${ISSUE_TITLE}" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+          BRANCH="feature/${ISSUE_NUM}-${SLUG}"
+
+          # Check dev branch exists
+          DEV_EXISTS=$(curl -sf -o /dev/null -w '%{http_code}' \
+            -H "Authorization: token ${TOKEN}" \
+            "${API}/branches/dev" 2>/dev/null || echo "000")
+
+          if [ "${DEV_EXISTS}" != "200" ]; then
+            echo "No dev branch -- skipping"
+            exit 0
+          fi
+
+          # Create branch from dev
+          HTTP=$(curl -sf -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${API}/branches" \
+            -d "{\"new_branch_name\":\"${BRANCH}\",\"old_branch_name\":\"dev\"}" 2>/dev/null || echo "000")
+
+          if [ "${HTTP}" = "201" ]; then
+            echo "Created branch: ${BRANCH}"
+
+            # Comment on issue with branch link
+            REPO_URL="${GITEA_URL}/${{ github.repository }}"
+            BODY="Branch created: [\`${BRANCH}\`](${REPO_URL}/src/branch/${BRANCH})\n\n\`\`\`bash\ngit fetch origin\ngit checkout ${BRANCH}\n\`\`\`"
+
+            curl -sf -X POST \
+              -H "Authorization: token ${TOKEN}" \
+              -H "Content-Type: application/json" \
+              "${API}/issues/${ISSUE_NUM}/comments" \
+              -d "{\"body\":\"${BODY}\"}" > /dev/null 2>&1
+
+            echo "Commented on issue #${ISSUE_NUM}"
+          else
+            echo "Failed to create branch (HTTP ${HTTP}) -- may already exist"
+          fi

.mokogitea/workflows/pr-check.yml

@@ -0,0 +1,236 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.CI
+# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
+# PATH: /templates/workflows/universal/pr-check.yml.template
+# VERSION: 05.00.00
+# BRIEF: PR gate — branch policy + code validation before merge
+
+name: "Universal: PR Check"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  # ── Branch Policy ──────────────────────────────────────────────────────
+  branch-policy:
+    name: Branch Policy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check branch merge target
+        run: |
+          HEAD="${{ github.head_ref }}"
+          BASE="${{ github.base_ref }}"
+
+          echo "PR: ${HEAD} → ${BASE}"
+
+          ALLOWED=true
+          REASON=""
+
+          case "$HEAD" in
+            feature/*|feat/*)
+              if [ "$BASE" != "dev" ]; then
+                ALLOWED=false
+                REASON="Feature branches must target 'dev', not '${BASE}'"
+              fi
+              ;;
+            fix/*|bugfix/*)
+              if [ "$BASE" != "dev" ]; then
+                ALLOWED=false
+                REASON="Fix branches must target 'dev', not '${BASE}'"
+              fi
+              ;;
+            patch/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "rc" ]; then
+                ALLOWED=false
+                REASON="Patch branches must target 'dev' or 'rc', not '${BASE}'"
+              fi
+              ;;
+            hotfix/*)
+              if [ "$BASE" != "dev" ] && [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="Hotfix branches can only target 'dev' or 'main', not '${BASE}'"
+              fi
+              ;;
+            rc)
+              if [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="RC branch can only merge into 'main', not '${BASE}'"
+              fi
+              ;;
+            dev)
+              if [ "$BASE" != "main" ]; then
+                ALLOWED=false
+                REASON="Dev branch can only merge into 'main', not '${BASE}'"
+              fi
+              ;;
+          esac
+
+          if [ "$ALLOWED" = false ]; then
+            echo "::error::${REASON}"
+            echo "## Branch Policy Violation" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "${REASON}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### Allowed merge paths:" >> $GITHUB_STEP_SUMMARY
+            echo "- \`feature/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`fix/*\` → \`dev\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`hotfix/*\` → \`dev\` or \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`dev\` → \`main\`" >> $GITHUB_STEP_SUMMARY
+            echo "- \`rc/*\` → \`main\`" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+
+          echo "Branch policy: OK (${HEAD} → ${BASE})"
+          echo "## Branch Policy: Passed" >> $GITHUB_STEP_SUMMARY
+
+  # ── Code Validation ────────────────────────────────────────────────────
+  validate:
+    name: Validate PR
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Detect platform
+        id: platform
+        run: |
+          # Read platform from XML manifest (<platform> tag) or plain text fallback
+          PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*/\1/p' .mokogitea/manifest.xml 2>/dev/null | head -1)
+          [ -z "$PLATFORM" ] && PLATFORM=$(cat .mokogitea/manifest.xml 2>/dev/null | tr -d '[:space:]')
+          [ -z "$PLATFORM" ] && PLATFORM="generic"
+          echo "platform=$PLATFORM" >> "$GITHUB_OUTPUT"
+
+      - name: Setup PHP
+        if: steps.platform.outputs.platform == 'joomla' || steps.platform.outputs.platform == 'dolibarr'
+        run: |
+          if ! command -v php &> /dev/null; then
+            sudo apt-get update -qq
+            sudo apt-get install -y -qq php-cli php-mbstring php-xml >/dev/null 2>&1
+          fi
+
+      - name: PHP syntax check
+        if: steps.platform.outputs.platform == 'joomla' || steps.platform.outputs.platform == 'dolibarr'
+        run: |
+          ERRORS=0
+          while IFS= read -r -d '' file; do
+            if ! php -l "$file" 2>&1 | grep -q "No syntax errors"; then
+              ERRORS=$((ERRORS + 1))
+            fi
+          done < <(find . -name "*.php" -not -path "./.git/*" -not -path "./vendor/*" -print0)
+          echo "PHP lint: ${ERRORS} error(s)"
+          [ "$ERRORS" -eq 0 ] || { echo "::error::PHP syntax errors found"; exit 1; }
+
+      - name: Validate platform manifest
+        run: |
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          case "$PLATFORM" in
+            joomla)
+              MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
+              if [ -z "$MANIFEST" ]; then
+                echo "::warning::No Joomla manifest found (WaaS site)"
+                exit 0
+              fi
+              echo "Manifest: ${MANIFEST}"
+              if command -v php &> /dev/null; then
+                php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('$MANIFEST'); if(!\$x){foreach(libxml_get_errors() as \$e) echo \$e->message; exit(1);}" || { echo "::error::Manifest XML is malformed"; exit 1; }
+              fi
+              for ELEMENT in name version description; do
+                grep -q "<${ELEMENT}>" "$MANIFEST" || { echo "::error::Missing <${ELEMENT}> in manifest"; exit 1; }
+              done
+              echo "Joomla manifest valid"
+              ;;
+            dolibarr)
+              MOD_FILE=$(find . -maxdepth 4 -name "mod*.class.php" ! -path "./.git/*" -exec grep -l 'extends DolibarrModules' {} \; 2>/dev/null | head -1)
+              if [ -z "$MOD_FILE" ]; then
+                echo "::error::No mod*.class.php found"
+                exit 1
+              fi
+              echo "Dolibarr module: ${MOD_FILE}"
+              ;;
+            *)
+              echo "Generic platform — no manifest validation"
+              ;;
+          esac
+
+      - name: Check update stream format
+        run: |
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          case "$PLATFORM" in
+            joomla)
+              if [ -f "updates.xml" ]; then
+                if command -v php &> /dev/null; then
+                  php -r "libxml_use_internal_errors(true); \$x = simplexml_load_file('updates.xml'); if(!\$x){foreach(libxml_get_errors() as \$e) echo \$e->message; exit(1);}" || { echo "::error::updates.xml is malformed"; exit 1; }
+                fi
+                echo "updates.xml valid"
+              fi
+              ;;
+            dolibarr)
+              [ -f "update.txt" ] && echo "update.txt present" || echo "::warning::No update.txt"
+              ;;
+          esac
+
+      - name: Check changelog has unreleased entry
+        run: |
+          if [ ! -f "CHANGELOG.md" ]; then
+            echo "::warning::No CHANGELOG.md found"
+            exit 0
+          fi
+          # Check for content under [Unreleased] section
+          if ! grep -q "## \[Unreleased\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md missing [Unreleased] section"
+            exit 1
+          fi
+          # Check there's at least one entry (Added/Changed/Fixed/Removed) under Unreleased
+          UNRELEASED_CONTENT=$(sed -n '/## \[Unreleased\]/,/## \[/p' CHANGELOG.md | grep -cE '^\s*-\s' || true)
+          if [ "$UNRELEASED_CONTENT" -eq 0 ]; then
+            echo "::error::CHANGELOG.md [Unreleased] section has no entries. Add a changelog entry describing your changes."
+            echo "## Changelog Check: Failed" >> $GITHUB_STEP_SUMMARY
+            echo "The \`[Unreleased]\` section in CHANGELOG.md has no entries." >> $GITHUB_STEP_SUMMARY
+            echo "Add a line like \`- Description of your change\` under a heading (\`### Added\`, \`### Changed\`, \`### Fixed\`, etc.)" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+          echo "Changelog: ${UNRELEASED_CONTENT} entry/entries in [Unreleased]"
+
+      - name: Verify package source
+        run: |
+          SOURCE_DIR="src"
+          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
+          if [ ! -d "$SOURCE_DIR" ]; then
+            echo "::warning::No src/ or htdocs/ directory"
+            exit 0
+          fi
+          FILE_COUNT=$(find "$SOURCE_DIR" -type f | wc -l)
+          echo "Source: ${FILE_COUNT} files"
+          [ "$FILE_COUNT" -gt 0 ] || { echo "::error::Source directory is empty"; exit 1; }
+
+  # ── Pre-Release RC Build ─────────────────────────────────────────────────
+  pre-release:
+    name: Build RC Package
+    runs-on: ubuntu-latest
+    needs: [branch-policy, validate]
+
+    steps:
+      - name: Trigger RC pre-release
+        env:
+          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          REPO: ${{ github.repository }}
+          BRANCH: ${{ github.head_ref }}
+          GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+        run: |
+          curl -s -X POST             "${GITEA_URL}/api/v1/repos/${REPO}/actions/workflows/pre-release.yml/dispatches"             -H "Authorization: token ${GITEA_TOKEN}"             -H "Content-Type: application/json"             -d "{\"ref\":\"${BRANCH}\",\"inputs\":{\"stability\":\"release-candidate\"}}"
+          echo "### Pre-Release" >> $GITHUB_STEP_SUMMARY
+          echo "Triggered RC build on branch \`${BRANCH}\`" >> $GITHUB_STEP_SUMMARY

.mokogitea/workflows/pre-release.yml

@@ -0,0 +1,233 @@
+# 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.MOKOGITEA_TOKEN }}
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+        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
+          # 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" \
+            /tmp/moko-platform-api
+          cd /tmp/moko-platform-api && composer install --no-dev --no-interaction --quiet
+          echo "MOKO_CLI=/tmp/moko-platform-api/cli" >> "$GITHUB_ENV"
+
+      - 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
+
+          # 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\)$//')
+
+          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
+          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
+
+          # 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://x-access-token:${{ secrets.MOKOGITEA_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}.zip"
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
+          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
+          echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"
+
+          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
+
+      - name: Create release
+        id: release
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          VERSION="${{ steps.meta.outputs.version }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php ${MOKO_CLI}/release_create.php \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --repo "${GITEA_REPO}" --branch dev --prerelease
+
+      - name: Build package and upload
+        id: package
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          TAG="${{ steps.meta.outputs.tag }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php ${MOKO_CLI}/release_package.php \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --repo "${GITEA_REPO}" --output /tmp || true
+
+      - name: Update updates.xml
+        if: steps.platform.outputs.platform == 'joomla'
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          SHA256="${{ steps.package.outputs.sha256_zip }}"
+
+          if [ ! -f "updates.xml" ]; then
+            echo "No updates.xml -- skipping"
+            exit 0
+          fi
+
+          SHA_FLAG=""
+          [ -n "$SHA256" ] && SHA_FLAG="--sha ${SHA256}"
+
+          php ${MOKO_CLI}/updates_xml_build.php \
+            --path . --version "${VERSION}" --stability "${STABILITY}" \
+            --gitea-url "${GITEA_URL}" --org "${GITEA_ORG}" --repo "${GITEA_REPO}" \
+            ${SHA_FLAG}
+
+          # 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}" -- updates.xml 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.MOKOGITEA_TOKEN }}"
+
+          php ${MOKO_CLI}/release_cascade.php \
+            --stability "${{ steps.meta.outputs.stability }}" \
+            --token "${TOKEN}" \
+            --api-base "${API_BASE}"
+
+      - name: Summary
+        if: always()
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          ZIP_NAME="${{ steps.meta.outputs.zip_name }}"
+          SHA256="${{ steps.package.outputs.sha256_zip }}"
+          echo "## Pre-Release Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Channel | ${STABILITY} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Package | \`${ZIP_NAME}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| SHA-256 | \`${SHA256:-n/a}\` |" >> $GITHUB_STEP_SUMMARY

.mokogitea/workflows/update-server.yml

@@ -0,0 +1,312 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Universal
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /templates/workflows/update-server.yml
+# VERSION: 05.00.00
+# BRIEF: Pre-release build + update server XML for dev/alpha/beta/rc branches
+#
+# Thin wrapper around moko-platform CLI tools.
+# Builds packages, updates updates.xml, and optionally deploys via SFTP.
+#
+# Joomla filters update entries by the 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 Server
+    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.MOKOGITEA_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          COMPOSER_AUTH: '{"http-basic":{"git.mokoconsulting.tech":{"username":"token","password":"${{ secrets.MOKOGITEA_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
+          # Always fetch latest CLI tools — never use stale cache from previous runs
+          rm -rf /tmp/moko-platform
+          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
+          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
+          echo "MOKO_CLI=/tmp/moko-platform/cli" >> "$GITHUB_ENV"
+
+      - name: Detect platform
+        id: platform
+        run: php ${MOKO_CLI}/manifest_read.php --path . --github-output
+
+      - name: Resolve stability and bump version
+        id: meta
+        run: |
+          BRANCH="${{ github.ref_name }}"
+
+          # Configure git for bot pushes
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+          # Auto-bump patch version
+          php ${MOKO_CLI}/version_bump.php --path . 2>/dev/null || true
+
+          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "0.0.0")
+
+          # Strip any existing suffix before applying stability
+          VERSION=$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
+
+          # Determine stability from branch or manual 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"
+          else
+            STABILITY="development"
+          fi
+
+          # Version suffix per stability stream
+          case "$STABILITY" in
+            development) SUFFIX="-dev";  TAG="development" ;;
+            alpha)       SUFFIX="-alpha"; TAG="alpha" ;;
+            beta)        SUFFIX="-beta";  TAG="beta" ;;
+            rc)          SUFFIX="-rc";    TAG="release-candidate" ;;
+            *)           SUFFIX="";       TAG="stable" ;;
+          esac
+
+          # Propagate version with stability suffix to all manifest files
+          php ${MOKO_CLI}/version_set_platform.php \
+            --path . --version "$VERSION" --branch "$BRANCH" --stability "$STABILITY" 2>/dev/null || true
+          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
+
+          # Re-read version (now includes suffix from version_set_platform)
+          if [ -n "$SUFFIX" ]; then
+            VERSION="${VERSION}${SUFFIX}"
+          fi
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
+          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "display_version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+          # Commit version bump if changed
+          git add -A
+          git diff --cached --quiet || {
+            git commit -m "chore(version): auto-bump ${VERSION} [skip ci]" \
+              --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>"
+            git push
+          }
+
+      - name: Create release and upload package
+        id: package
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          TAG="${{ steps.meta.outputs.tag }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+
+          # Create or update Gitea release
+          php ${MOKO_CLI}/release_create.php \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --repo "${GITEA_REPO}" --branch "${{ github.ref_name }}" --prerelease
+
+          # Build package and upload
+          php ${MOKO_CLI}/release_package.php \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --repo "${GITEA_REPO}" --output /tmp || true
+
+      - name: Update updates.xml
+        if: steps.platform.outputs.platform == 'joomla'
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          SHA256="${{ steps.package.outputs.sha256_zip }}"
+
+          if [ ! -f "updates.xml" ]; then
+            echo "No updates.xml — skipping"
+            exit 0
+          fi
+
+          SHA_FLAG=""
+          [ -n "$SHA256" ] && SHA_FLAG="--sha ${SHA256}"
+
+          php ${MOKO_CLI}/updates_xml_build.php \
+            --path . --version "${VERSION}" --stability "${STABILITY}" \
+            --gitea-url "${GITEA_URL}" --org "${GITEA_ORG}" --repo "${GITEA_REPO}" \
+            ${SHA_FLAG}
+
+          # Commit and push updates.xml
+          git add updates.xml
+          git diff --cached --quiet || {
+            git commit -m "chore: update ${STABILITY} channel ${VERSION} [skip ci]"
+            git push
+          }
+
+      - name: Sync updates.xml to main
+        if: github.ref_name != 'main' && steps.platform.outputs.platform == 'joomla'
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          GITEA_TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
+
+          FILE_SHA=$(curl -sf -H "Authorization: token ${GITEA_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 ${{ steps.meta.outputs.stability }} [skip ci]',
+              'branch': 'main'
+          }).encode()
+          req = urllib.request.Request(
+              '${API_BASE}/contents/updates.xml',
+              data=payload, method='PUT',
+              headers={
+                  'Authorization': 'token ${GITEA_TOKEN}',
+                  'Content-Type': 'application/json'
+              })
+          try:
+              urllib.request.urlopen(req)
+              print('updates.xml synced to main')
+          except Exception as e:
+              print(f'WARNING: sync to main failed: {e}', file=sys.stderr)
+          "
+          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 }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+
+          PERMISSION=$(curl -sf -H "Authorization: token ${{ secrets.MOKOGITEA_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 ${MOKO_CLI}/platform_detect.php --path . 2>/dev/null || true)
+          if [ "$PLATFORM" = "waas-component" ] && [ -f "${MOKO_CLI}/../deploy/deploy-joomla.php" ]; then
+            php ${MOKO_CLI}/../deploy/deploy-joomla.php --path . --src-dir "$SOURCE_DIR" --config /tmp/sftp-config.json
+          elif [ -f "${MOKO_CLI}/../deploy/deploy-sftp.php" ]; then
+            php ${MOKO_CLI}/../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: Summary
+        if: always()
+        run: |
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          DISPLAY="${{ steps.meta.outputs.display_version }}"
+          echo "## 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}\` |" >> $GITHUB_STEP_SUMMARY

CLAUDE.md

@@ -56,6 +56,8 @@ make clean        # Clean build artifacts
 
 ## 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

CONTRIBUTING.md

@@ -1,245 +1,161 @@
-<!--
- 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
-
- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License (./LICENSE).
- 
- # FILE INFORMATION
- DEFGROUP: MokoStandards-Template-Joomla-Plugin
- INGROUP: MokoStandards-Template-Joomla-Plugin.Documentation
- REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-Template-Joomla-Plugin/
- VERSION: 01.00.00
- PATH: ./CONTRIBUTING.md
- BRIEF: How to contribute; commit, PR, testing and security policies
- NOTE: Template repository - customize for your project
- -->
-# Contributing
-
-Thank you for your interest in contributing. This document defines the baseline expectations, workflows, and quality gates for any change entering this repository.
-
-The objective is to keep contributions predictable, reviewable, and compliant with MokoStandards while enabling a sustainable delivery pipeline.
-
-## Governance and scope
-
-This CONTRIBUTING file operates alongside the following governance assets:
-
-* `README.md` for project overview and onboarding
-* `LICENSE` for legal terms and reuse constraints
-* `CODE_OF_CONDUCT.md` for behavioral expectations
-
-In case of conflict, legal terms in `LICENSE` take precedence, followed by this document.
-
-## Alignment with MokoStandards
-
-All Moko Consulting projects are expected to comply with the shared standards defined in the `MokoStandards` repository.
-
-* Source of truth: [https://github.com/mokoconsulting-tech/MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards)
-* Areas covered: headers, licensing, coding style, documentation layout, and CI expectations
-
-Per project policy, this file should reference standards rather than redefining them. Any deviation must be explicitly documented.
-
-## Ways to contribute
-
-Contributions are welcome across multiple workstreams:
-
-* Bug reports and defect reproduction scenarios
-* Feature requests aligned with the project roadmap
-* Code changes, including refactors and technical debt reduction
-* Documentation improvements and clarifications
-* Test coverage (unit, integration, and regression scenarios)
-
-Before investing significant effort, contributors are encouraged to review the open issues and roadmap documents to avoid misalignment.
-
-## Communication channels
-
-Typical communication paths include:
-
-* GitHub Issues for bug reports, feature requests, and questions
-* GitHub Discussions for design conversations, Q&A, and community engagement
-* Pull Requests for change proposals
-
-## Issue workflow
-
-Use GitHub Issues as the system of record for all work.
-
-When opening an issue:
-
-1. Search existing issues to avoid duplication.
-2. Select the appropriate issue template if available.
-3. Provide a concise, action oriented title.
-4. Supply a clear description including:
-
-	* Expected behavior
-	* Actual behavior
-	* Minimal steps to reproduce
-	* Environment details (version, platform, configuration)
-5. Attach logs, screenshots, or configuration snippets as needed, after removing sensitive data.
-
-Maintainers will triage issues based on impact, risk, and alignment with the roadmap. Not all requests will be accepted, but all will be reviewed in good faith.
-
-## Pull request workflow
-
-Pull Requests (PRs) are the primary integration path for changes.
-
-Standard workflow:
-
-1. Open or reference an issue describing the problem or enhancement.
-2. Fork the repository or create a feature branch from the canonical default branch (commonly `main` or `master`).
-3. Implement changes aligned with the coding standards and file header requirements.
-4. Add or update tests to validate the behavior.
-5. Update documentation where behavior, configuration, or interfaces change.
-6. Run the full test and linting suite locally before opening the PR.
-7. Open a PR with:
-
-	* A precise, descriptive title
-	* A summary of changes
-	* Explicit linkage to the corresponding issue
-	* Notes on testing performed and any known limitations
-
-PRs must pass automated checks before they will be considered for review. The maintainer team reserves the right to request revisions, split changes, or defer work that does not align with the current release plan.
-
-## Merge strategy
-
-This repository uses **squash merge** as the only permitted merge method for pull requests to the main branch. This ensures a clean, linear git history where each commit represents a complete, reviewed change.
-
-Key implications for contributors:
-
-* **PR Title is Important**: The PR title becomes the commit message subject. Make it clear and descriptive.
-* **PR Description is Important**: The PR description becomes the commit message body. Include rationale and summary of changes.
-* **Automatic Cleanup**: Branches are automatically deleted after merge.
-* **No Merge Commits**: Regular merge commits and rebase merges are disabled.
-
-## Branching and versioning
-
-Unless specified otherwise:
-
-* Default development branch: `main`
-* Feature work: short lived feature branches named using a predictable convention, for example `feature/<short-description>` or `fix/<short-description>`
-* Releases: tagged using semantic versioning (`MAJOR.MINOR.PATCH`)
-
-## Coding standards and file headers
-
-This project adheres to the coding conventions and header rules defined in MokoStandards. At a minimum:
-
-* All source and configuration files must include the standard SPDX compatible header where applicable.
-* Language specific style guides (for example PHP, JavaScript, Python) must be followed.
-* Follow Joomla coding standards for PHP code.
-
-## Commit message guidelines
-
-Commit messages are part of the project audit trail. They should be structured and descriptive.
-
-Recommended format:
-
-* Short subject line in the imperative mood, for example `Add`, `Fix`, `Refactor`
-* Optional body that explains the rationale, constraints, and side effects
-* Reference to related issues using `Fixes #<id>` or `Refs #<id>` as appropriate
-
-Avoid bundling unrelated changes into a single commit. Small, logically grouped commits improve traceability and rollback options.
-
-## Testing expectations
-
-Before opening a PR, contributors are expected to:
-
-* Run all available automated tests (unit, integration, and other configured checks)
-* Ensure linting and static analysis pass without new violations
-* Test changes with a local Joomla installation when applicable
-
-For new features or non trivial fixes, please include tests that:
-
-* Reproduce the defect, or
-* Demonstrate the new behavior
-
-If tests are not included, the PR should clearly state why (for example, infrastructure limitations, complex external dependencies, or pure documentation changes).
-
-## Documentation contributions
-
-Documentation is a first class asset in this ecosystem.
-
-When contributing documentation:
-
-* Align with the established docs hierarchy (for example `docs/`)
-* Apply the shared template structure for new documents
-* Include appropriate navigation, metadata, and revision history sections when required by the documentation standards
-
-Minor corrections such as typo fixes are welcome, but larger structural changes should be coordinated via an issue or design note first.
-
-## Security and responsible disclosure
-
-Security sensitive issues must not be reported in public issues.
-
-Use the security contact channel defined in `SECURITY.md` to share details.
-
-Provide enough information for maintainers to reproduce and understand the impact. The team will coordinate fixes and disclosure timelines as appropriate.
-
-## License and contributor agreement
-
-Unless stated otherwise, contributions to this repository are accepted under the same license as the project, GPL 3.0 or later.
-
-By submitting a contribution, you confirm that:
-
-* You have the right to contribute the code or content.
-* You agree that your contribution will be licensed under the project license.
-* You will not submit content that infringes third party rights.
-
-## Escalation and decision making
-
-If you disagree with a review decision or prioritization decision:
-
-1. Escalate by commenting on the issue or PR with your reasoning.
-2. Request a second review from a different maintainer.
-3. Contact the project maintainers directly via the channels listed in README.md.
-
-Final decisions rest with the project maintainers, but all concerns will be considered fairly.
-
----
-
-## Contact
-
-For questions or clarifications about this contributing guide:
-
-* Open a GitHub Issue
-* Contact: hello@mokoconsulting.tech
-
-Thank you for contributing to this project and supporting the MokoStandards ecosystem!
-
-## Infrastructure Standards
-
-All repositories in the MokoConsulting org follow these conventions:
-
-### Release Tags
-
-Every repo maintains 5 standard release channel tags:
-
-- `development` - Active development builds
-- `alpha` - Early internal testing
-- `beta` - Broader testing / client UAT
-- `release-candidate` - Final QA before production
-- `stable` - Production release
-
-### Branch Protection
-
-- `main` is protected; only `jmiller` can push directly
-- All other contributors must use pull requests
-- PRs are automatically reviewed by Claude Code
-
-### CI/CD
-
-- Gitea Actions runs all CI workflows
-- GitHub Actions are disabled on mirrored repos
-- Workflows live in both `.github/workflows/` and `.gitea/workflows/`
-
-### Update Servers (Joomla)
-
-In manifest `<updateservers>`, Gitea must be priority 1, GitHub priority 2.
-
-### Secrets
-
-All repos have `GA_TOKEN` and `GH_TOKEN` as Actions secrets for API access.
+# Contributing to Moko Consulting Projects
+
+Thank you for your interest in contributing. All Moko Consulting repositories follow this universal workflow and version policy.
+
+## Branching Workflow
+
+```
+feature/* ──PR──> dev ──draft PR──> (renamed to rc) ──merge──> main
+```
+
+### Step by step
+
+1. **Create a feature branch** from `dev`:
+   ```bash
+   git checkout dev && git pull
+   git checkout -b feature/my-change
+   ```
+
+2. **Work and commit** on your feature branch. Push to origin.
+
+3. **Open a PR**: `feature/my-change` → `dev`. After review and checks, merge it.
+
+4. **When ready for release**, open a **draft PR**: `dev` → `main`.
+   - This automatically renames the source branch to `rc` (release candidate)
+   - An RC pre-release is built and uploaded
+
+5. **Alpha and beta branches** are created by manually renaming the branch before the RC stage:
+   - Rename `dev` to `alpha` for early testing → alpha pre-release is built
+   - Rename `alpha` to `beta` for feature-complete testing → beta pre-release is built
+   - When the draft PR is created, the branch is renamed to `rc`
+
+6. **Once PR checks pass** on the `rc` branch, mark the PR as ready and merge to `main`.
+
+7. **Merging to main** triggers the stable release pipeline:
+   - Minor version bump (e.g., `02.09.xx` → `02.10.00`)
+   - Stability suffix stripped (clean version)
+   - Gitea release created with ZIP/tar.gz packages
+   - `updates.xml` updated (Joomla extensions)
+   - `dev` branch recreated from `main`
+
+### Branch summary
+
+| Branch | Purpose | Created by |
+|--------|---------|-----------|
+| `feature/*` | New features and fixes | Developer |
+| `dev` | Integration branch | Auto-recreated after release |
+| `alpha` | Alpha pre-release testing | Manual rename from `dev` |
+| `beta` | Beta pre-release testing | Manual rename from `alpha` |
+| `rc` | Release candidate | Auto-renamed on draft PR to main |
+| `main` | Stable releases | Protected, merge only |
+| `version/XX.YY.ZZ` | Archived release snapshots | Auto-created by CI |
+
+### Protected branches
+
+| Branch | Direct push | Merge via |
+|--------|------------|-----------|
+| `main` | Blocked (CI bot whitelisted) | PR merge only |
+| `dev` | Blocked (CI bot whitelisted) | PR merge from feature/* |
+| `rc` | Blocked (CI bot whitelisted) | Auto-created on draft PR |
+| `alpha` | Blocked (CI bot whitelisted) | Manual rename |
+| `beta` | Blocked (CI bot whitelisted) | Manual rename |
+| `feature/*` | Open | N/A (source branch) |
+
+## Version Policy
+
+### Format
+
+All versions use `XX.YY.ZZ` — three two-digit segments, zero-padded:
+
+- **XX** — Major version (breaking changes)
+- **YY** — Minor version (new features, bumped on release to main)
+- **ZZ** — Patch version (auto-incremented on every push to dev/feature branches)
+
+Rollover: patch `99` → `00` increments minor; minor `99` → `00` increments major.
+
+### Stability suffixes
+
+Each branch appends a suffix to indicate stability:
+
+| Branch | Suffix | Example |
+|--------|--------|---------|
+| `main` | (none) | `02.09.00` |
+| `dev` | `-dev` | `02.09.01-dev` |
+| `feature/*` | `-dev` | `02.09.01-dev` |
+| `alpha` | `-alpha` | `02.09.01-alpha` |
+| `beta` | `-beta` | `02.09.01-beta` |
+| `rc` | `-rc` | `02.09.01-rc` |
+
+### Auto version bump
+
+On every push to `dev`, `feature/*`, or `patch/*`:
+
+1. Patch version incremented
+2. Stability suffix `-dev` applied
+3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.)
+4. Commit created with `[skip ci]` to avoid loops
+
+### Release version flow
+
+Version bumps happen at specific release events:
+
+| Event | Bump | Example |
+|-------|------|---------|
+| Feature merged to dev | Patch bump after dev release | `02.09.01-dev` → release → `02.09.02-dev` |
+| Dev promoted to RC | Minor bump | `02.09.02-dev` → `02.10.00-rc` |
+| RC merged to main | Minor bump | `02.10.00-rc` → `02.11.00` (stable) |
+| Dev recreated from main | Patch bump | `02.11.00` → `02.11.01-dev` |
+
+### Release stream copies
+
+When a higher-stability release is published, copies are created for all lesser streams with the same base version:
+
+- **RC `02.10.00-rc`** also creates: `02.10.00-dev`, `02.10.00-alpha`, `02.10.00-beta`
+- **Stable `02.11.00`** also creates: `02.11.00-dev`, `02.11.00-alpha`, `02.11.00-beta`, `02.11.00-rc`
+
+This ensures Joomla sites on ANY stability channel see the update (Joomla only shows versions higher than what's installed).
+
+### Version files
+
+The version tools update all files containing version stamps:
+
+- `.mokogitea/manifest.xml` (canonical source)
+- Joomla XML manifests (`<version>` tag)
+- `README.md`, `CHANGELOG.md` (`VERSION:` pattern)
+- `package.json`, `pyproject.toml`
+- Any text file with a `VERSION: XX.YY.ZZ` label
+
+Files synced from other repos (with a `# REPO:` header) are not touched.
+
+## Code Standards
+
+- **PHP**: PSR-12, tabs for indentation
+- **Copyright**: all files must include the Moko Consulting copyright header
+- **License**: SPDX identifier `GPL-3.0-or-later` (or as specified per repo)
+- **Attribution**: use `Authored-by: Moko Consulting` in commits, not individual names
+
+## Commit Messages
+
+Use conventional commit format:
+
+```
+type(scope): short description
+
+Optional body with context.
+
+Authored-by: Moko Consulting
+```
+
+Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `ci`
+
+Special flags in commit messages:
+- `[skip ci]` — skip all CI workflows
+- `[skip bump]` — skip auto version bump only
+
+## Reporting Issues
+
+Use the repository's issue tracker with the appropriate template.
+
+---
+
+*Moko Consulting <hello@mokoconsulting.tech>*