chore: sync security-audit.yml from Template-Generic [skip ci]

chore: sync pre-release.yml from Template-Generic [skip ci]
chore: sync notify.yml from Template-Generic [skip ci]
2026-06-07 17:55:58 +00:00 · 2026-06-07 17:55:57 +00:00 · 2026-06-07 17:55:55 +00:00 · 2026-06-07 17:55:54 +00:00 · 2026-06-07 17:55:53 +00:00 · 2026-06-07 17:55:51 +00:00
63 changed files with 1917 additions and 925 deletions
@@ -1,194 +0,0 @@
 # Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
 # INGROUP: MokoStandards.CI
 # REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
 # 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
              ;;
            hotfix/*)
              if [ "$BASE" != "dev" ] && [ "$BASE" != "main" ]; then
                ALLOWED=false
                REASON="Hotfix branches can only target 'dev' or 'main', not '${BASE}'"
              fi
              ;;
            alpha/*|beta/*)
              if [ "$BASE" != "dev" ]; then
                ALLOWED=false
                REASON="Pre-release branches must target 'dev', not '${BASE}'"
              fi
              ;;
            rc/*)
              if [ "$BASE" != "main" ]; then
                ALLOWED=false
                REASON="Release candidate branches must target '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: |
          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: 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; }
@@ -0,0 +1,48 @@
 ---
 name: API Integration Request
 about: Request integration with a new REST API or service
 title: '[API] '
 labels: 'enhancement, api-integration'
 assignees: ''
 ---
 ## API Integration Request
 ### Target API
 - **Service Name**: [e.g., Akeeba Backup, Joomla Web Services]
 - **API Documentation**: [URL to API docs]
 - **API Type**: [REST / GraphQL / SOAP]
 - **Authentication**: [API Key / OAuth / Bearer Token / Basic Auth]
 ### Proposed Tools
 List the MCP tools this integration would provide:
 | Tool Name | HTTP Method | Endpoint | Description |
 |---|---|---|---|
 | `service_list` | GET | `/api/items` | List all items |
 | `service_get` | GET | `/api/items/{id}` | Get single item |
 | `service_create` | POST | `/api/items` | Create item |
 ### Multi-Connection
 - [ ] Single instance only
 - [ ] Multiple instances (production, staging, dev)
 - [ ] Multi-tenant (one connection per client)
 ### Use Case
 Describe the workflow this integration enables for AI assistants.
 ### Priority
 - [ ] Critical — blocking current work
 - [ ] High — needed soon
 - [ ] Medium — would improve workflow
 - [ ] Low — nice to have
 ### Existing Alternatives
 Are there other ways to accomplish this today? If so, why is an MCP integration better?
 ### Checklist
 - [ ] API documentation is available and accessible
 - [ ] API supports the required authentication method
 - [ ] I have tested the API endpoints manually
 - [ ] The integration follows the Template-MCP architecture pattern
@@ -0,0 +1,67 @@
 ---
 name: MCP Connection Issue
 about: Report a connection, authentication, or API communication issue
 title: '[CONNECTION] '
 labels: 'bug, mcp-connection'
 assignees: ''
 ---
 ## Connection Issue
 ### Issue Type
 - [ ] Authentication failure (401/403)
 - [ ] Connection refused / timeout
 - [ ] TLS / SSL certificate error
 - [ ] Wrong connection used (wrong environment)
 - [ ] Config file not found / parse error
 - [ ] API response error (4xx / 5xx)
 ### MCP Server
 - **Server Name**: [e.g., mcp_mokowaas]
 - **Server Version**: [e.g., 1.0.0]
 - **Node.js Version**: [e.g., 20.x]
 ### Connection Details
 - **Connection Name**: [e.g., production, staging, default]
 - **API Base URL**: [e.g., https://api.example.com] *(do not include API keys)*
 - **Insecure Mode**: [Yes / No]
 ### Error Message
 ```
 Paste the exact error message here
 ```
 ### Steps to Reproduce
 1. Configure connection with `npm run setup`
 2. Call tool `...` with parameters `...`
 3. See error
 ### Expected Behavior
 What should have happened.
 ### Debugging Attempted
 - [ ] Tested API directly with curl
 - [ ] Verified API key is valid
 - [ ] Checked config file exists and is valid JSON
 - [ ] Tested with `list_connections` tool
 - [ ] Ran server manually: `node dist/index.js 2> debug.log`
 ### Config File
 ```json
 {
  "defaultConnection": "...",
  "connections": {
    "connection_name": {
      "baseUrl": "https://...",
      "apiKey": "REDACTED"
    }
  }
 }
 ```
 *(Redact all API keys and tokens)*
 ### Environment
 - **OS**: [e.g., macOS 14, Ubuntu 22.04, Windows 11]
 - **Claude Code Version**: [e.g., latest]
 - **Registration**: [.mcp.json / ~/.claude.json]
@@ -0,0 +1,49 @@
 ---
 name: New MCP Tool Request
 about: Request a new tool to be added to this MCP server
 title: '[TOOL] '
 labels: 'enhancement, mcp-tool'
 assignees: ''
 ---
 ## Tool Request
 ### Tool Name
 Proposed tool name (snake_case): `resource_action`
 ### Description
 What should this tool do? What API endpoint(s) does it map to?
 ### API Endpoint(s)
 - **Method**: [GET / POST / PUT / PATCH / DELETE]
 - **Endpoint**: `/api/v1/...`
 - **Auth**: [API Key / Token / None]
 ### Parameters
 | Parameter | Type | Required | Description |
 |---|---|---|---|
 | `id` | number | Yes | Resource ID |
 | `search` | string | No | Search filter |
 ### Expected Response
 ```json
 {
  "id": 1,
  "name": "Example"
 }
 ```
 ### Use Case
 Describe when and why someone would use this tool from Claude or another AI assistant.
 ### Connection Scope
 - [ ] Works with all connections
 - [ ] Specific to certain API versions
 - [ ] Requires additional permissions
 ### Checklist
 - [ ] I have checked this tool does not already exist
 - [ ] I have verified the API endpoint exists and is documented
 - [ ] The proposed name follows the `resource_action` convention
@@ -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
@@ -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"
@@ -171,10 +171,27 @@ jobs:
            echo MOKO_CLI=/tmp/moko-platform-api/cli >> $GITHUB_ENV
          fi
      - name: "Determine version bump level"
        id: bump
        run: |
          # Fix/patch branches: version was already bumped by pre-release, just strip suffix
          # Feature/dev branches: bump minor for the new stable release
          HEAD_REF="${{ github.event.pull_request.head.ref || 'dev' }}"
          case "$HEAD_REF" in
            fix/*|patch/*|hotfix/*|bugfix/*) BUMP="none" ;;
            *)                               BUMP="minor" ;;
          esac
          echo "level=${BUMP}" >> "$GITHUB_OUTPUT"
          echo "Bump level: ${BUMP} (from branch: ${HEAD_REF})"
      - name: "Publish stable release"
        run: |
          BUMP_FLAG=""
          if [ "${{ steps.bump.outputs.level }}" != "none" ]; then
            BUMP_FLAG="--bump ${{ steps.bump.outputs.level }}"
          fi
          php ${MOKO_CLI}/release_publish.php \
-            --path . --stability stable --bump minor --branch main \
+            --path . --stability stable ${BUMP_FLAG} --branch main \
            --token "${{ secrets.MOKOGITEA_TOKEN }}"
      - name: Update release notes from CHANGELOG.md
@@ -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
@@ -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"
@@ -0,0 +1,204 @@
 # Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
 # INGROUP: MokoStandards.CI
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
 # PATH: /.gitea/workflows/ci-generic.yml
 # VERSION: 01.00.00
 # BRIEF: CI pipeline — lint, validate, and test for generic projects (PHP + Node.js)
 name: "Generic: Project CI"
 on:
  push:
    branches:
      - main
      - dev
      - dev/**
      - rc/**
      - version/**
  pull_request:
    branches:
      - main
      - dev
      - dev/**
      - rc/**
  workflow_dispatch:
 permissions:
  contents: read
 env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 jobs:
  # ── Lint & Validate ───────────────────────────────────────────────────
  lint:
    name: Lint & Validate
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Detect toolchain
        id: detect
        run: |
          HAS_PHP=false
          HAS_NODE=false
          [ -f "composer.json" ] && HAS_PHP=true
          [ -f "package.json" ] && HAS_NODE=true
          echo "has_php=$HAS_PHP" >> "$GITHUB_OUTPUT"
          echo "has_node=$HAS_NODE" >> "$GITHUB_OUTPUT"
          echo "Toolchain: PHP=$HAS_PHP Node=$HAS_NODE"
      - name: Setup PHP
        if: steps.detect.outputs.has_php == 'true'
        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
          php -v
      - name: Setup Node.js
        if: steps.detect.outputs.has_node == 'true'
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install PHP dependencies
        if: steps.detect.outputs.has_php == 'true'
        run: |
          if [ -f "composer.json" ]; then
            composer install --no-interaction --prefer-dist --quiet 2>/dev/null || true
          fi
      - name: Install Node.js dependencies
        if: steps.detect.outputs.has_node == 'true'
        run: |
          if [ -f "package.json" ]; then
            npm ci --quiet 2>/dev/null || npm install --quiet 2>/dev/null || true
          fi
      - name: PHP syntax check
        if: steps.detect.outputs.has_php == 'true'
        run: |
          ERRORS=0
          while IFS= read -r -d '' file; do
            if ! php -l "$file" 2>&1 | grep -q "No syntax errors"; then
              echo "::error file=${file}::PHP syntax error"
              ERRORS=$((ERRORS + 1))
            fi
          done < <(find . -name "*.php" -not -path "./.git/*" -not -path "./vendor/*" -not -path "./node_modules/*" -print0)
          echo "## PHP Lint" >> $GITHUB_STEP_SUMMARY
          if [ "$ERRORS" -eq 0 ]; then
            echo "All PHP files passed syntax check." >> $GITHUB_STEP_SUMMARY
          else
            echo "${ERRORS} file(s) with syntax errors." >> $GITHUB_STEP_SUMMARY
            exit 1
          fi
      - name: TypeScript/JavaScript lint
        if: steps.detect.outputs.has_node == 'true'
        run: |
          if [ -f "node_modules/.bin/eslint" ]; then
            npx eslint src/ --quiet 2>&1 || { echo "::error::ESLint errors found"; exit 1; }
            echo "## ESLint" >> $GITHUB_STEP_SUMMARY
            echo "All files passed ESLint." >> $GITHUB_STEP_SUMMARY
          elif [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] || [ -f "eslint.config.js" ]; then
            echo "::warning::ESLint config found but eslint not installed"
          else
            echo "No ESLint configured — skipping"
          fi
      - name: TypeScript compile check
        if: steps.detect.outputs.has_node == 'true'
        run: |
          if [ -f "tsconfig.json" ] && [ -f "node_modules/.bin/tsc" ]; then
            npx tsc --noEmit 2>&1 || { echo "::error::TypeScript compilation errors"; exit 1; }
            echo "## TypeScript" >> $GITHUB_STEP_SUMMARY
            echo "TypeScript compilation passed." >> $GITHUB_STEP_SUMMARY
          fi
      - name: PHPStan static analysis
        if: steps.detect.outputs.has_php == 'true'
        run: |
          if [ -f "phpstan.neon" ] && [ -f "vendor/bin/phpstan" ]; then
            vendor/bin/phpstan analyse --no-progress 2>&1 || { echo "::warning::PHPStan found issues"; }
          fi
  # ── Tests ─────────────────────────────────────────────────────────────
  test:
    name: Tests
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Detect toolchain
        id: detect
        run: |
          HAS_PHP=false
          HAS_NODE=false
          [ -f "composer.json" ] && HAS_PHP=true
          [ -f "package.json" ] && HAS_NODE=true
          echo "has_php=$HAS_PHP" >> "$GITHUB_OUTPUT"
          echo "has_node=$HAS_NODE" >> "$GITHUB_OUTPUT"
      - name: Setup PHP
        if: steps.detect.outputs.has_php == 'true'
        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: Setup Node.js
        if: steps.detect.outputs.has_node == 'true'
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: |
          [ -f "composer.json" ] && composer install --no-interaction --prefer-dist --quiet 2>/dev/null || true
          [ -f "package.json" ] && { npm ci --quiet 2>/dev/null || npm install --quiet 2>/dev/null || true; }
      - name: Run PHP tests
        if: steps.detect.outputs.has_php == 'true'
        run: |
          if [ -f "vendor/bin/phpunit" ]; then
            vendor/bin/phpunit --testdox 2>&1
            echo "## PHPUnit" >> $GITHUB_STEP_SUMMARY
            echo "Tests passed." >> $GITHUB_STEP_SUMMARY
          elif [ -f "phpunit.xml" ] || [ -f "phpunit.xml.dist" ]; then
            echo "::warning::PHPUnit config found but phpunit not installed"
          else
            echo "No PHPUnit configured — skipping"
          fi
      - name: Run Node.js tests
        if: steps.detect.outputs.has_node == 'true'
        run: |
          if jq -e '.scripts.test' package.json > /dev/null 2>&1; then
            npm test 2>&1
            echo "## Node.js Tests" >> $GITHUB_STEP_SUMMARY
            echo "Tests passed." >> $GITHUB_STEP_SUMMARY
          else
            echo "No test script in package.json — skipping"
          fi
      - name: Build check
        run: |
          if [ -f "Makefile" ]; then
            make build 2>&1 || echo "::warning::Build failed or not configured"
          elif [ -f "package.json" ] && jq -e '.scripts.build' package.json > /dev/null 2>&1; then
            npm run build 2>&1 || echo "::warning::Build failed"
          fi
@@ -0,0 +1,87 @@
 # Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
 # INGROUP: MokoStandards.Maintenance
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
 # PATH: /.gitea/workflows/cleanup.yml
 # VERSION: 01.00.00
 # BRIEF: Scheduled cleanup — delete merged branches and old workflow runs
 name: "Universal: Repository Cleanup"
 on:
  schedule:
    - cron: '0 3 * * 0'  # Weekly on Sunday at 03:00 UTC
  workflow_dispatch:
 permissions:
  contents: write
 env:
  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
 jobs:
  cleanup:
    name: Clean Merged Branches
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GA_TOKEN }}
      - name: Delete merged branches
        env:
          GA_TOKEN: ${{ secrets.GA_TOKEN }}
        run: |
          echo "=== Merged Branch Cleanup ==="
          API="${GITEA_URL}/api/v1/repos/${{ github.repository }}"
          # List branches via API
          BRANCHES=$(curl -sS -H "Authorization: token ${GA_TOKEN}" \
            "${API}/branches?limit=50" | jq -r '.[].name')
          DELETED=0
          for BRANCH in $BRANCHES; do
            # Skip protected branches
            case "$BRANCH" in
              main|master|develop|release/*|hotfix/*) continue ;;
            esac
            # Check if branch is merged into main
            if git merge-base --is-ancestor "origin/${BRANCH}" origin/main 2>/dev/null; then
              echo "  Deleting merged branch: ${BRANCH}"
              curl -sS -X DELETE -H "Authorization: token ${GA_TOKEN}" \
                "${API}/branches/${BRANCH}" 2>/dev/null || true
              DELETED=$((DELETED + 1))
            fi
          done
          echo "Deleted ${DELETED} merged branch(es)"
      - name: Clean old workflow runs
        env:
          GA_TOKEN: ${{ secrets.GA_TOKEN }}
        run: |
          echo "=== Workflow Run Cleanup ==="
          API="${GITEA_URL}/api/v1/repos/${{ github.repository }}"
          CUTOFF=$(date -d "30 days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -v-30d +%Y-%m-%dT%H:%M:%SZ)
          # Get old completed runs
          RUNS=$(curl -sS -H "Authorization: token ${GA_TOKEN}" \
            "${API}/actions/runs?status=completed&limit=50" | \
            jq -r ".workflow_runs[] | select(.created_at < \"${CUTOFF}\") | .id" 2>/dev/null)
          DELETED=0
          for RUN_ID in $RUNS; do
            curl -sS -X DELETE -H "Authorization: token ${GA_TOKEN}" \
              "${API}/actions/runs/${RUN_ID}" 2>/dev/null || true
            DELETED=$((DELETED + 1))
          done
          echo "Deleted ${DELETED} old workflow run(s)"
@@ -0,0 +1,126 @@
 # Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
 # INGROUP: MokoStandards.Deploy
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
 # PATH: /templates/workflows/joomla/deploy-manual.yml.template
 # VERSION: 04.07.00
 # BRIEF: Manual SFTP deploy to dev server for Joomla repos
 name: "Universal: Deploy to Dev (Manual)"
 on:
  workflow_dispatch:
    inputs:
      clear_remote:
        description: 'Delete all remote files before uploading'
        required: false
        default: 'false'
        type: boolean
 env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 permissions:
  contents: read
 jobs:
  deploy:
    name: SFTP Deploy to Dev
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - name: Setup PHP
        run: |
          php -v && composer --version
      - name: Setup MokoStandards tools
        env:
          GA_TOKEN: ${{ secrets.GA_TOKEN || secrets.GA_TOKEN || github.token }}
          MOKO_CLONE_TOKEN: ${{ secrets.GA_TOKEN || secrets.GA_TOKEN || github.token }}
          MOKO_CLONE_HOST: ${{ secrets.GA_TOKEN && 'git.mokoconsulting.tech/MokoConsulting' || 'github.com/mokoconsulting-tech' }}
          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GA_TOKEN || github.token }}"}}'
        run: |
          git clone --depth 1 --branch main --quiet \
            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/MokoStandards-API.git" \
            /tmp/mokostandards-api 2>/dev/null || true
          if [ -d "/tmp/mokostandards-api" ] && [ -f "/tmp/mokostandards-api/composer.json" ]; then
            cd /tmp/mokostandards-api && composer install --no-dev --no-interaction --quiet 2>/dev/null || true
          fi
      - name: Check FTP configuration
        id: check
        env:
          HOST: ${{ vars.DEV_FTP_HOST }}
          PATH_VAR: ${{ vars.DEV_FTP_PATH }}
          PORT: ${{ vars.DEV_FTP_PORT }}
        run: |
          if [ -z "$HOST" ] || [ -z "$PATH_VAR" ]; then
            echo "DEV_FTP_HOST or DEV_FTP_PATH not configured -- cannot deploy"
            echo "skip=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "skip=false" >> "$GITHUB_OUTPUT"
          echo "host=$HOST" >> "$GITHUB_OUTPUT"
          REMOTE="${PATH_VAR%/}"
          echo "remote=$REMOTE" >> "$GITHUB_OUTPUT"
          [ -z "$PORT" ] && PORT="22"
          echo "port=$PORT" >> "$GITHUB_OUTPUT"
      - name: Deploy via SFTP
        if: steps.check.outputs.skip != 'true'
        env:
          SFTP_KEY: ${{ secrets.DEV_FTP_KEY }}
          SFTP_PASS: ${{ secrets.DEV_FTP_PASSWORD }}
          SFTP_USER: ${{ vars.DEV_FTP_USERNAME }}
        run: |
          SOURCE_DIR="src"
          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
          [ ! -d "$SOURCE_DIR" ] && { echo "No src/ or htdocs/ -- nothing to deploy"; exit 0; }
          printf '{"host":"%s","port":%s,"username":"%s","remotePath":"%s"' \
            "${{ steps.check.outputs.host }}" "${{ steps.check.outputs.port }}" "$SFTP_USER" "${{ steps.check.outputs.remote }}" \
            > /tmp/sftp-config.json
          if [ -n "$SFTP_KEY" ]; then
            echo "$SFTP_KEY" > /tmp/deploy_key
            chmod 600 /tmp/deploy_key
            printf ',"privateKeyPath":"/tmp/deploy_key"}' >> /tmp/sftp-config.json
          else
            printf ',"password":"%s"}' "$SFTP_PASS" >> /tmp/sftp-config.json
          fi
          DEPLOY_ARGS=(--path . --src-dir "$SOURCE_DIR" --config /tmp/sftp-config.json)
          [ "${{ inputs.clear_remote }}" = "true" ] && DEPLOY_ARGS+=(--clear-remote)
          PLATFORM=$(php /tmp/mokostandards-api/cli/platform_detect.php --path . 2>/dev/null || true)
          if [ "$PLATFORM" = "waas-component" ] && [ -f "/tmp/mokostandards-api/deploy/deploy-joomla.php" ]; then
            php /tmp/mokostandards-api/deploy/deploy-joomla.php "${DEPLOY_ARGS[@]}"
          else
            php /tmp/mokostandards-api/deploy/deploy-sftp.php "${DEPLOY_ARGS[@]}"
          fi
          rm -f /tmp/deploy_key /tmp/sftp-config.json
      - name: Summary
        if: always()
        run: |
          if [ "${{ steps.check.outputs.skip }}" = "true" ]; then
            echo "### Deploy Skipped -- FTP not configured" >> $GITHUB_STEP_SUMMARY
          else
            echo "### Manual Dev Deploy Complete" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
            echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
            echo "| Host | \`${{ steps.check.outputs.host }}\` |" >> $GITHUB_STEP_SUMMARY
            echo "| Remote | \`${{ steps.check.outputs.remote }}\` |" >> $GITHUB_STEP_SUMMARY
            echo "| Clear | ${{ inputs.clear_remote }} |" >> $GITHUB_STEP_SUMMARY
          fi
@@ -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
@@ -6,7 +6,7 @@
 # DEFGROUP: Gitea.Workflow
 # INGROUP: MokoStandards.Notifications
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
-# PATH: /.mokogitea/workflows/notify.yml
+# PATH: /.gitea/workflows/notify.yml
 # VERSION: 01.00.00
 # BRIEF: Push notifications via ntfy on release success or workflow failure
@@ -18,7 +18,6 @@ on:
      - "Joomla Build & Release"
      - "Joomla Extension CI"
      - "Deploy"
      - "Cascade Main → Dev"
    types:
      - completed
@@ -8,236 +8,4 @@
 # 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
+# BRIEF: Auto pre-release on push to dev/alpha/beta/rc branches
 name: "Universal: Pre-Release"
 on:
  pull_request:
    types: [closed]
    branches:
      - dev
  pull_request_target:
    types: [synchronize, opened, reopened]
    branches:
      - main
  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_name == 'pull_request' && github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev') ||
      (github.event_name == 'pull_request_target' && github.event.pull_request.base.ref == 'main')
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.MOKOGITEA_TOKEN }}
          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || '' }}
      - name: Setup moko-platform tools
        env:
          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
        run: |
          # Use pre-installed /opt/moko-platform if available (updated by cron every 6h)
          if [ -f /opt/moko-platform/cli/version_bump.php ] && [ -f /opt/moko-platform/cli/manifest_element.php ] && [ -f /opt/moko-platform/vendor/autoload.php ]; then
            echo Using pre-installed /opt/moko-platform
            echo MOKO_CLI=/opt/moko-platform/cli >> $GITHUB_ENV
          else
            echo Falling back to fresh clone
            if ! command -v composer > /dev/null 2>&1; then
              sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
            fi
            rm -rf /tmp/moko-platform-api
            CLONE_URL=https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git
            git clone --depth 1 --branch main --quiet $CLONE_URL /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: Detect platform
        id: platform
        run: |
          php ${MOKO_CLI}/manifest_read.php --path . --github-output
      - name: Resolve metadata and bump version
        id: meta
        run: |
          # Auto-detect stability: RC for PRs targeting main, else use input or default to development
          if [ "${{ github.event_name }}" = "pull_request_target" ] && [ "${{ github.event.pull_request.base.ref }}" = "main" ]; then
            STABILITY="release-candidate"
          else
            STABILITY="${{ inputs.stability || 'development' }}"
          fi
          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
          # Bump version via CLI: patch for dev/alpha/beta, minor for RC
          case "$STABILITY" in
            release-candidate) BUMP="minor" ;;
            *)                 BUMP="patch" ;;
          esac
          php ${MOKO_CLI}/version_bump.php --path . $([ "$BUMP" = "minor" ] && echo "--minor") 2>/dev/null || true
          # Set stability suffix and verify consistency
          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "00.00.01")
          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
          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
          # Ensure licensing tags (updateservers, dlid) if enabled in manifest.xml
          php ${MOKO_CLI}/manifest_licensing.php --path . --fix 2>/dev/null || true
          # Append suffix for output
          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: Update release notes from CHANGELOG.md
        run: |
          TAG="${{ steps.meta.outputs.tag }}"
          VERSION="${{ steps.meta.outputs.version }}"
          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
          # Extract [Unreleased] section from changelog (everything between [Unreleased] and next ## heading)
          if [ -f "CHANGELOG.md" ]; then
            NOTES=$(awk '/^## \[Unreleased\]/{found=1; next} /^## \[/{if(found) exit} found{print}' CHANGELOG.md)
            [ -z "$NOTES" ] && NOTES="Release ${VERSION}"
          else
            NOTES="Release ${VERSION}"
          fi
          # Update release body via API
          RELEASE_ID=$(curl -sf -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \
            "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
          if [ -n "$RELEASE_ID" ]; then
            python3 -c "
          import json, urllib.request
          body = open('/dev/stdin').read()
          payload = json.dumps({'body': body}).encode()
          req = urllib.request.Request(
              '${API_BASE}/releases/${RELEASE_ID}',
              data=payload, method='PATCH',
              headers={
                  'Authorization': 'token ${{ secrets.MOKOGITEA_TOKEN }}',
                  'Content-Type': 'application/json'
              })
          urllib.request.urlopen(req)
          " <<< "$NOTES"
            echo "Release notes updated from CHANGELOG.md"
          fi
      - 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
      # updates.xml is generated dynamically by MokoGitea license server
      # No need to build, commit, or sync updates.xml from workflows
      - 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
@@ -6,7 +6,7 @@
 # DEFGROUP: Gitea.Workflow
 # INGROUP: MokoStandards.Security
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
-# PATH: /.mokogitea/workflows/security-audit.yml
+# PATH: /.gitea/workflows/security-audit.yml
 # VERSION: 01.00.00
 # BRIEF: Dependency vulnerability scanning for composer and npm packages
@@ -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
@@ -1,4 +1,30 @@
 <!--	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: dolibarr-api-mcp.Documentation
 	INGROUP: dolibarr-api-mcp
 	REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
 	VERSION: 01.00.00
 	PATH: ./CHANGELOG.md
 	BRIEF: Version history and change log
 -->
 # Changelog
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
@@ -9,3 +35,36 @@
 ### Added
 - `branch-cleanup.yml`: auto-delete merged feature branches after PR merge
 ## [0.0.1] - 2026-05-07
 ### Added
 - Initial MCP server with Dolibarr REST API tools
 - Third party management (list, get, create, update, delete)
 - Invoice management (list, get, create, add lines, validate, set paid)
 - Commercial proposal management (list, get, create, add lines, validate, close)
 - Customer order management (list, get, create, validate)
 - Product and service catalog (list, get, create, update, stock levels)
 - Contact/address management (list, get)
 - Project management (list, get, create)
 - Task management (list, get)
 - User management (list, get)
 - Category management (list by type)
 - Bank account listing
 - Supplier invoice listing
 - Supplier order listing
 - Warehouse listing
 - Company setup and system status endpoints
 - Raw API passthrough for any Dolibarr endpoint
 - Multi-connection support with named connections
 - Interactive setup wizard (`npm run setup`)
 - SQL filter builder (`buildSqlFilter`, `searchFilter`) for safe query construction
 - Full documentation: README, INSTALLATION, ARCHITECTURE, API reference
 - MokoStandards-compliant project structure
 - 12 Gitea Actions CI/CD workflows
 ## Revision History
 | Date | Version | Author | Notes |
 | --- | --- | --- | --- |
 | 2026-05-07 | 0.0.1 | jmiller | Initial release |
@@ -33,6 +33,8 @@ This is an MCP (Model Context Protocol) server. Key files:
 ## 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
@@ -1,161 +1,161 @@
-<!--	Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+# Contributing to Moko Consulting Projects
-	This file is part of a Moko Consulting project.
+Thank you for your interest in contributing. All Moko Consulting repositories follow this universal workflow and version policy.
-	SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
+## Branching Workflow
-	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.
+```
 feature/* ──PR──> dev ──draft PR──> (renamed to rc) ──merge──> main
 ```
-	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.
+### Step by step
-	You should have received a copy of the GNU General Public License (./LICENSE).
+1. **Create a feature branch** from `dev`:
   ```bash
   git checkout dev && git pull
   git checkout -b feature/my-change
   ```
-	# FILE INFORMATION
+2. **Work and commit** on your feature branch. Push to origin.
 	DEFGROUP: dolibarr-api-mcp.Documentation
 	INGROUP: dolibarr-api-mcp
 	REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
 	VERSION: 01.00.00
 	PATH: ./CONTRIBUTING.md
 	BRIEF: Contribution guidelines for the project
 -->
-# Contributing to dolibarr-api-mcp
+3. **Open a PR**: `feature/my-change` → `dev`. After review and checks, merge it.
-We appreciate your interest in contributing to this project! This document provides guidelines for contributing.
+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
-## Table of Contents
+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`
- [Code of Conduct](#code-of-conduct)
+6. **Once PR checks pass** on the `rc` branch, mark the PR as ready and merge to `main`.
 - [Getting Started](#getting-started)
 - [How to Contribute](#how-to-contribute)
 - [Development Workflow](#development-workflow)
 - [Commit Messages](#commit-messages)
 - [Pull Request Process](#pull-request-process)
-## Code of Conduct
+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`
-This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to hello@mokoconsulting.tech.
+### Branch summary
-## Getting Started
+| 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 |
-1. Fork the repository
+### Protected branches
 2. Clone your fork locally
 3. Install dependencies: `npm install`
 4. Build: `npm run build`
 5. Create a new branch for your work
-## How to Contribute
+| 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) |
-### Reporting Bugs
+## Version Policy
- Use the Gitea issue tracker
+### Format
 - Describe the bug clearly with steps to reproduce
 - Include the Dolibarr version you're connecting to
 - Include relevant logs or error messages
-### Adding New Tools
+All versions use `XX.YY.ZZ` — three two-digit segments, zero-padded:
-If you want to add support for a Dolibarr API endpoint not yet covered:
+- **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)
-1. Check the [Dolibarr API Explorer](https://your-dolibarr.com/api/index.php/explorer) for endpoint details
+Rollover: patch `99` → `00` increments minor; minor `99` → `00` increments major.
 2. Add the tool registration in `src/index.ts` following the existing patterns
 3. Update `docs/API.md` with the new tool's parameter table
 4. Update `README.md` tool listing
 5. Update `CHANGELOG.md`
-### Contributing Code
+### Stability suffixes
- Pick an issue or create one
+Each branch appends a suffix to indicate stability:
 - Fork the repository and create a branch
 - Make your changes following the project conventions
 - Submit a pull request
-## Development Workflow
+| 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` |
-1. Ensure your fork is up to date with the main repository
+### Auto version bump
-2. Create a feature branch from `main`
+
-3. Make your changes
+On every push to `dev`, `feature/*`, or `patch/*`:
-4. Test against a Dolibarr instance (use `npm run setup` to configure a dev connection)
+
-5. Build with `npm run build` to catch TypeScript errors
+1. Patch version incremented
-6. Commit your changes with clear messages
+2. Stability suffix `-dev` applied
-7. Push to your fork
+3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.)
-8. Create a pull request
+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
-Follow the conventional commit format:
+Use conventional commit format:
 ```
-<type>(<scope>): <subject>
+type(scope): short description
-<body>
+Optional body with context.
-<footer>
+Authored-by: Moko Consulting
 ```
-Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`, `revert`
+Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `ci`
-Example:
+Special flags in commit messages:
-```
+- `[skip ci]` — skip all CI workflows
-feat(tools): add shipment management tools
+- `[skip bump]` — skip auto version bump only
-Add dolibarr_shipments_list, dolibarr_shipment_get, and
+## Reporting Issues
 dolibarr_shipment_validate tools for the /shipments API endpoint.
 ```
-## Pull Request Process
+Use the repository's issue tracker with the appropriate template.
-1. Update documentation for any new tools
+---
 2. Follow the project's coding style and conventions
 3. Ensure `npm run build` succeeds without errors
 4. Update the CHANGELOG.md with your changes
 5. Request review from maintainers
 6. Address any feedback promptly
 7. Once approved, your PR will be merged
-## Style Guidelines
+*Moko Consulting <hello@mokoconsulting.tech>*
 - Use tabs for indentation
 - All source files must include the Moko Consulting copyright header
 - Use `snake_case` for local variables (matching Dolibarr API field names)
 - Use Zod for all tool parameter validation
 - Follow the `formatResponse()` pattern for consistent error handling
 ## 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
 - Workflows live in `.gitea/workflows/`
 ### Secrets
 All repos have `GA_TOKEN` and `GH_TOKEN` as Actions secrets for API access.
 ## Questions?
 If you have questions about contributing, feel free to open an issue or contact the maintainers at hello@mokoconsulting.tech.
 ## Revision History
 | Date | Version | Author | Notes |
 | --- | --- | --- | --- |
 | 2026-05-07 | 0.0.1 | jmiller | Initial contributing guidelines |