chore: add .mokogitea/branch-protection.yml from moko-platform [skip ci]

# Conflicts:
#	.mokogitea/manifest.xml

.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/manifest.xml

@@ -8,14 +8,14 @@
     <name>MokoWaaS</name>
     <org>MokoConsulting</org>
     <description>White-label identity, security hardening, and tenant restriction layer for WaaS-managed Joomla environments</description>
-    <version>02.18.00</version>
+    <version>02.20.00</version>
     <license spdx="GPL-3.0-or-later">GNU General Public License v3</license>
   </identity>
   <governance>
     <platform>joomla</platform>
     <standards-version>05.00.00</standards-version>
     <standards-source>https://git.mokoconsulting.tech/MokoConsulting/moko-platform</standards-source>
-    <last-synced>2026-05-21T20:48:00+00:00</last-synced>
+    <last-synced>2026-05-28T20:00:00+00:00</last-synced>
   </governance>
   <build>
     <language>PHP</language>

.mokogitea/workflows/auto-bump.yml

@@ -1,85 +1,67 @@
-# 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
-
-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: |
-          BUMP=$(php ${MOKO_CLI}/version_bump.php --path . 2>&1) || true
-          echo "$BUMP"
-
-          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null) || true
-          [ -z "$VERSION" ] && { echo "No version found — skipping"; exit 0; }
-
-          # Propagate to platform manifests with -dev suffix
-          php ${MOKO_CLI}/version_set_platform.php \
-            --path . --version "$VERSION" --branch dev --stability dev 2>/dev/null || true
-          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
-          VERSION="${VERSION}-dev"
-
-          # Commit if anything changed
-          if git diff --quiet && git diff --cached --quiet; then
-            echo "No version changes to commit"
-            exit 0
-          fi
-
-          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 commit -m "chore(version): auto-bump patch ${VERSION} [skip ci]" \
-            --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>"
-          git push origin dev
-          echo "Bumped to ${VERSION}" >> $GITHUB_STEP_SUMMARY
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Release
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /.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
+      - alpha
+      - beta
+      - rc
+      - 'feature/**'
+
+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/branch-cleanup.yml

@@ -33,7 +33,7 @@ jobs:
         run: |
           BRANCH="${{ github.event.pull_request.head.ref }}"
           API="${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}/api/v1/repos/${{ github.repository }}/branches"
-          ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('${BRANCH}', safe=''))")
+          ENCODED=$(php -r "echo rawurlencode('${BRANCH}');")
 
           STATUS=$(curl -sf -o /dev/null -w "%{http_code}" -X DELETE \
             -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \

.mokogitea/workflows/update-server.yml

@@ -114,6 +114,9 @@ jobs:
 
           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 }}"

CHANGELOG.md

@@ -21,6 +21,12 @@
 # Changelog
 ## [Unreleased]
 
+## [02.20.00] --- 2026-05-28
+
+## [02.20.00] --- 2026-05-28
+
+## [02.19.00] --- 2026-05-28
+
 ## [02.18.00] --- 2026-05-28
 
 
@@ -55,72 +61,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - updates.xml: removed stale pre-release entries pointing to non-existent dev artifacts, legacy plugin update entry that caused stable sites to attempt dev downloads
 - Removed duplicate `<updateservers>` from inner plugin manifest — only the package-level manifest should register the update server
 - Auto-cleanup of stale plugin-level update site entries on install/update (cleans `#__update_sites` and `#__update_sites_extensions`)
-
-## [02.06.00] - 2026-05-25
-
-### Added
-- Alias offline bypass: aliases with offline=No override Joomla's global offline setting, allowing access via alias domain while main site is down
-- Block non-master users from viewing or editing MokoWaaS plugin settings
-- Master user bypasses ALL tenant restrictions (install from URL, global config, sysinfo, installer, templates)
-- Admin Help menu redirected to configured support URL (replaces help.joomla.org)
-
-### Fixed
-- Install API endpoint: extract ZIP to temp directory before passing to Joomla Installer (was passing ZIP path directly)
-- Clean up extracted temp directory on success or failure
-- Update site disabled by Joomla when protected=1 — ensureProtectedFlag() now re-enables it
-- CI: auto-release fetches updates.xml from main before building (preserves all channels)
-- CI: version_check.php --fix runs after version bump in both workflows
-- CI: checksums attached as `[filename].sha256` files instead of in release body
-- CI: auto-release cleaned up — removed duplicate asset loops, inline Python updater, dead code
-- CI: Step 8b uses `release_body_update.php` CLI instead of inline Python
-- CI: Step 6 tag creation no longer gated by `is_minor` (was never set)
-
-### Changed
-- CI: auto-release uses stream tag `stable` instead of version tag `vXX`
-- CI: pre-release package build uses absolute paths (fixes relative path zip error)
-
-## [02.05.00] - 2026-05-24
-
-### Added
-- Joomla `protected=1` flag on all MokoWaaS extensions (framework-level disable/uninstall prevention)
-- Self-healing protected flag — restored each admin session if cleared
-- Block non-master disable via plugin list toggle (`plugins.publish`)
-- Package script sets `protected=1, locked=0` on every install/update
-- Legacy plugin entry in updates.xml for sites upgrading from standalone plugin
-
-### Fixed
-- CI: auto-release workflow `pkg_pkg_` duplication in release names, ZIP filenames, and SHA256 paths
-- CI: auto-release now strips existing type prefix and uses `<packagename>` for packages
-- CI: `updates_xml_build` was cascading entries for all lower channels on stable release — now writes only current channel
-- CI: `targetplatform` regex `((5.[0-9])|(6.[0-9]))` caused Gitea 500 on XML render — simplified to `(5|6)\..*`
-- updates.xml stable entry now has correct `<tag>stable</tag>` and download URL
-- README slimmed to overview, detailed content moved to wiki
-
-## [02.03.10] - 2026-05-24
-
-### Added
-- Canonical URL injection for alias domains (prevents SEO duplication)
-- Primary Domain config field in Site Aliases tab
-- Heartbeat registration for alias domains (each alias gets Grafana datasource)
-- Plugin protection: hidden from non-master users, disable/uninstall blocked
-- Dynamic plugin version read from manifest XML (no more hardcoded strings)
-- Package structure: `pkg_mokowaas` with system plugin, webservices plugin, and component
-
-### Changed
-- Alias offline mode uses Joomla's native template offline.php (not custom HTML)
-- Alias detection simplified: direct lookup in aliases list (no primary host comparison)
-- handleSiteAlias() moved to onAfterRoute (client type resolved at that point)
-- Package script.php enables plugins on every install/update and sends heartbeat
-
-### Fixed
-- Alias domain matching: strip trailing slashes, handle Joomla subform stdClass format
-- Backend redirect: use primary_domain setting instead of Uri::root() (returned alias domain on mirrors)
-- CI: version_bump reads manifest XML with priority over README.md VERSION header
-- CI: version bump occurs after release build, not before
-- CI: pipefail disabled during element detection (SIGPIPE on find|head)
-- CI: pkg_pkg_ prefix duplication in zip names and updates.xml URLs
-- CI: updates_xml_build preserves existing channel entries (stable not wiped by dev releases)
-
-### Removed
-- deploy-manual.yml workflow — using Joomla update server for distribution
-- Accidentally committed profile.ps1 and TODO.md

CONTRIBUTING.md

@@ -1,93 +1,141 @@
-<!--
- Copyright (C) 2025 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.md).
+# Contributing to Moko Consulting Projects
 
- # FILE INFORMATION
- DEFGROUP: Joomla.Plugin
- INGROUP: MokoWaaS.Contributing
- REPO: https://github.com/mokoconsulting-tech/mokowaas
- VERSION: 02.01.08
- PATH: /CONTRIBUTING.md
- BRIEF: Contribution guidelines for the MokoWaaS plugin
--->
+Thank you for your interest in contributing. All Moko Consulting repositories follow this universal workflow and version policy.
 
-# Contributing to MokoWaaS (VERSION: 02.01.08)
+## Branching Workflow
 
-## Overview
-Contributions to the MokoWaaS plugin follow standardized development, governance, and quality control expectations defined by Moko Consulting. This document outlines contribution requirements, acceptable change types, branch management, testing expectations, and release readiness standards.
+```
+feature/* ──PR──> dev ──draft PR──> (renamed to rc) ──merge──> main
+```
 
-## 1. Contribution Workflow
-All contributions must follow the established workflow:
-1. Fork the repository or create a feature branch (if internal).
-2. Ensure your environment matches the supported Joomla and PHP versions.
-3. Implement changes following coding, documentation, and metadata standards.
-4. Validate plugin functionality locally.
-5. Submit a Pull Request (PR) for review.
+### Step by step
 
-## 2. Branching Model
-- `main`: Production stable branch.
-- `develop`: Aggregates work for the next minor release.
-- `feature/*`: New enhancements or changes.
-- `bugfix/*`: Hotfixes and corrections.
+1. **Create a feature branch** from `dev`:
+   ```bash
+   git checkout dev && git pull
+   git checkout -b feature/my-change
+   ```
 
-Internal teams must coordinate with governance before creating major feature branches.
+2. **Work and commit** on your feature branch. Push to origin.
 
-## 3. Coding and Documentation Standards
-All code must:
-- Follow [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) coding standards
-- Include the unified SPDX license header
-- Include a FILE INFORMATION metadata block
-- Avoid deprecated Joomla APIs
-- Preserve load order compatibility with other system plugins
+3. **Open a PR**: `feature/my-change` → `dev`. After review and checks, merge it.
 
-Documentation must:
-- Include metadata
-- Maintain revision history
-- Use consistent formatting as defined by Moko documentation standards
+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
 
-## 4. Testing Requirements
-Before submitting a PR, contributors must verify:
-- Plugin installs successfully in Joomla 5.x
-- No load errors appear in logs
-- Branding replacements appear as expected
-- Terminology strings are correct
-- No regressions in administrator UI
+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`
 
-Automated testing coverage will expand as part of future roadmap enhancements.
+6. **Once PR checks pass** on the `rc` branch, mark the PR as ready and merge to `main`.
 
-## 5. Pull Request Requirements
-A PR must include:
-- Description of change
-- Screenshots for UI related updates
-- Version updates when appropriate
-- Notes for documentation changes
-- Reference to related issues or tasks
+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`
 
-PRs lacking required information may be flagged or delayed.
+### Branch summary
 
-## 6. Release Versioning
-Changes must follow semantic versioning:
-- MAJOR: Structural branding or architectural changes
-- MINOR: Feature updates or terminology expansion
-- PATCH: Bug fixes or language corrections
+| 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 |
 
-Version updates must be reflected in:
-- Manifest files
-- PHP headers
-- Documentation metadata
+### Protected branches
 
-## 7. Code Review Standards
-Reviewers validate:
-- Code quality and clarity
-- Compliance with [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards) coding standards
-- Impact to templates and WaaS branding rules
-- Backwards compatibility expectations
+| 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) |
 
-## Revision History
-| Date | Author | Description |
-| ------ | -------- | ----------- |
-| 2025-12-11 | Jonathan Miller (@jmiller-moko) | Initial creation of contribution guidelines |
+## 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`, `alpha`, `beta`, `rc`, or `feature/*`:
+
+1. Patch version incremented
+2. Stability suffix applied based on branch name
+3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.)
+4. Commit created with `[skip ci]` to avoid loops
+
+### 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>*

README.md

@@ -9,7 +9,7 @@
  DEFGROUP: Joomla.Plugin
  INGROUP: MokoWaaS
  REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS
- VERSION: 02.18.00
+ VERSION: 02.21.00
  PATH: /README.md
  BRIEF: MokoWaaS platform plugin for Joomla
 -->

src/packages/com_mokowaas/mokowaas.xml

@@ -7,7 +7,7 @@
 	<license>GPL-3.0-or-later</license>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>
 	<authorUrl>https://mokoconsulting.tech</authorUrl>
-	<version>02.18.00</version>
+	<version>02.20.00</version>
 	<description>Minimal API-only component for MokoWaaS. Provides REST endpoints for site health, cache, updates, and backups.</description>
 	<namespace path="api/src">Moko\Component\MokoWaaS\Api</namespace>
 	<administration>

src/packages/plg_system_mokowaas/mokowaas.xml

@@ -30,7 +30,7 @@
 	<license>GNU General Public License version 3 or later; see LICENSE.md</license>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>
 	<authorUrl>https://mokoconsulting.tech</authorUrl>
-	<version>02.18.00</version>
+	<version>02.20.00</version>
 	<description>This plugin rebrands the Joomla system interface with MokoWaaS identity. It applies language overrides and ensures consistent branding across the platform.</description>
 	<namespace path=".">Moko\Plugin\System\MokoWaaS</namespace>
 	<scriptfile>script.php</scriptfile>

src/packages/plg_webservices_mokowaas/mokowaas.xml

@@ -7,7 +7,7 @@
 	<license>GPL-3.0-or-later</license>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>
 	<authorUrl>https://mokoconsulting.tech</authorUrl>
-	<version>02.18.00</version>
+	<version>02.20.00</version>
 	<description>Joomla Web Services API routes for MokoWaaS site management — health checks, cache, updates, backups, and site info.</description>
 	<namespace path="src">Moko\Plugin\WebServices\MokoWaaS</namespace>
 	<files>

src/packages/plg_webservices_perfectpublisher/perfectpublisher.xml

@@ -7,7 +7,7 @@
 	<license>GPL-3.0-or-later</license>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>
 	<authorUrl>https://mokoconsulting.tech</authorUrl>
-	<version>02.18.00</version>
+	<version>02.20.00</version>
 	<description>Joomla Web Services API routes for Perfect Publisher (com_autotweet) — channels, posts, requests, rules, and feeds.</description>
 	<namespace path="src">Moko\Plugin\WebServices\PerfectPublisher</namespace>
 	<files>

src/pkg_mokowaas.xml

@@ -2,7 +2,7 @@
 <extension type="package" method="upgrade">
 	<name>MokoWaaS</name>
 	<packagename>mokowaas</packagename>
-	<version>02.18.00</version>
+	<version>02.20.00</version>
 	<creationDate>2026-05-23</creationDate>
 	<author>Moko Consulting</author>
 	<authorEmail>hello@mokoconsulting.tech</authorEmail>

updates.xml

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
  SPDX-License-Identifier: GPL-3.0-or-later
- VERSION: 02.18.00
+ VERSION: 02.20.00
  -->
 
 <updates>
@@ -11,13 +11,13 @@
     <element>pkg_mokowaas</element>
     <type>package</type>
     <client>site</client>
-    <version>02.18.00</version>
+    <version>02.20.00</version>
     <creationDate>2026-05-28</creationDate>
     <infourl title='Package - MokoWaaS'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/tag/stable</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.18.00.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.20.00.zip</downloadurl>
     </downloads>
-    <sha256>69806f038bdb396cee15b2419ff04382f36d83b824db32928296743a04ea6c86</sha256>
+    <sha256>4f893125c1f66d5c8545191d081a3f8abf555a7c0fe84f00b3be3cdda532b38f</sha256>
     <tags><tag>dev</tag></tags>
     <maintainer>Moko Consulting</maintainer>
     <maintainerurl>https://mokoconsulting.tech</maintainerurl>
@@ -29,13 +29,13 @@
     <element>pkg_mokowaas</element>
     <type>package</type>
     <client>site</client>
-    <version>02.18.00</version>
+    <version>02.20.00</version>
     <creationDate>2026-05-28</creationDate>
     <infourl title='Package - MokoWaaS'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/tag/stable</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.18.00.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.20.00.zip</downloadurl>
     </downloads>
-    <sha256>69806f038bdb396cee15b2419ff04382f36d83b824db32928296743a04ea6c86</sha256>
+    <sha256>4f893125c1f66d5c8545191d081a3f8abf555a7c0fe84f00b3be3cdda532b38f</sha256>
     <tags><tag>alpha</tag></tags>
     <maintainer>Moko Consulting</maintainer>
     <maintainerurl>https://mokoconsulting.tech</maintainerurl>
@@ -47,13 +47,13 @@
     <element>pkg_mokowaas</element>
     <type>package</type>
     <client>site</client>
-    <version>02.18.00</version>
+    <version>02.20.00</version>
     <creationDate>2026-05-28</creationDate>
     <infourl title='Package - MokoWaaS'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/tag/stable</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.18.00.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.20.00.zip</downloadurl>
     </downloads>
-    <sha256>69806f038bdb396cee15b2419ff04382f36d83b824db32928296743a04ea6c86</sha256>
+    <sha256>4f893125c1f66d5c8545191d081a3f8abf555a7c0fe84f00b3be3cdda532b38f</sha256>
     <tags><tag>beta</tag></tags>
     <maintainer>Moko Consulting</maintainer>
     <maintainerurl>https://mokoconsulting.tech</maintainerurl>
@@ -65,13 +65,13 @@
     <element>pkg_mokowaas</element>
     <type>package</type>
     <client>site</client>
-    <version>02.18.00</version>
+    <version>02.20.00</version>
     <creationDate>2026-05-28</creationDate>
     <infourl title='Package - MokoWaaS'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/tag/stable</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.18.00.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.20.00.zip</downloadurl>
     </downloads>
-    <sha256>69806f038bdb396cee15b2419ff04382f36d83b824db32928296743a04ea6c86</sha256>
+    <sha256>4f893125c1f66d5c8545191d081a3f8abf555a7c0fe84f00b3be3cdda532b38f</sha256>
     <tags><tag>rc</tag></tags>
     <maintainer>Moko Consulting</maintainer>
     <maintainerurl>https://mokoconsulting.tech</maintainerurl>
@@ -83,13 +83,13 @@
     <element>pkg_mokowaas</element>
     <type>package</type>
     <client>site</client>
-    <version>02.18.00</version>
+    <version>02.20.00</version>
     <creationDate>2026-05-28</creationDate>
     <infourl title='Package - MokoWaaS'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/tag/stable</infourl>
     <downloads>
-      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.18.00.zip</downloadurl>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/releases/download/stable/pkg_mokowaas-02.20.00.zip</downloadurl>
     </downloads>
-    <sha256>69806f038bdb396cee15b2419ff04382f36d83b824db32928296743a04ea6c86</sha256>
+    <sha256>4f893125c1f66d5c8545191d081a3f8abf555a7c0fe84f00b3be3cdda532b38f</sha256>
     <tags><tag>stable</tag></tags>
     <maintainer>Moko Consulting</maintainer>
     <maintainerurl>https://mokoconsulting.tech</maintainerurl>