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

Runner image has stale /opt/moko-platform missing manifest_element.php.
Adding it to the existence check forces a fresh clone until the image
is rebuilt.

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

.mokogitea/CLAUDE.md

@@ -0,0 +1,76 @@
+# moko-platform
+
+Enterprise automation, validation, sync, and governance engine for all Moko Consulting repositories.
+
+## Quick Reference
+
+| Field | Value |
+|---|---|
+| **Language** | PHP 8.1+ |
+| **Version** | 09.01.00 |
+| **Branch** | develop on `dev`, merge to `main` (protected) |
+| **Wiki** | [moko-platform Wiki](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki) |
+
+## Commands
+
+```bash
+composer install                         # Install PHP dependencies
+php bin/moko health --path .             # Repo health check
+php bin/moko check:syntax --path .       # PHP syntax check
+php bin/moko drift --org MokoConsulting  # Scan for standards drift
+php bin/moko dashboard --token $TOKEN -o dashboard.html  # Client dashboard
+
+# Code quality
+php vendor/bin/phpcs --standard=phpcs.xml -n lib/ validate/ automation/ cli/
+php vendor/bin/phpcbf --standard=phpcs.xml lib/ validate/ automation/ cli/
+php vendor/bin/phpstan analyse -c phpstan.neon --memory-limit=512M
+composer check                           # Run all checks
+```
+
+## Architecture
+
+| Directory | Purpose |
+|---|---|
+| `cli/` | 32 standalone CLI tools (version, release, build, repo management) |
+| `validate/` | 20 validation scripts (syntax, structure, manifests, drift) |
+| `automation/` | 7 bulk operations (sync, push files, templates, cleanup) |
+| `lib/Enterprise/` | Core library — CliFramework, ApiClient, adapters, validators |
+| `lib/Enterprise/Plugins/` | 11 platform plugins (Joomla, Dolibarr, Node.js, Python, etc.) |
+| `deploy/` | SFTP deployment scripts (Joomla, Dolibarr, health checks) |
+| `templates/` | Universal templates, configs, governance schema |
+| `.mokogitea/workflows/` | CI/CD workflows (Gitea Actions) |
+| `bin/moko` | Unified CLI dispatcher — `php bin/moko <command>` |
+| `monitoring/sites.json` | Sites list for mcp_mokomonitor |
+
+### CLI Framework
+
+All CLI tools extend `MokoEnterprise\CliFramework` (`lib/Enterprise/CliFramework.php`).
+Built-in flags: `--help`, `--verbose`, `--quiet`, `--dry-run`.
+After adding a CLI tool, register it in `bin/moko` COMMAND_MAP.
+
+### Platform Adapters
+
+- `MokoGiteaAdapter` — git.mokoconsulting.tech (primary)
+- `GitHubAdapter` — github.com mirrors
+
+### Plugin System
+
+Platform-specific logic in `lib/Enterprise/Plugins/`. Each implements `ProjectPluginInterface` with health checks, validation, build commands, config schemas.
+
+## Code Quality
+
+| Tool | Level | Config |
+|---|---|---|
+| PHPCS | PSR-12 (errors only) | `phpcs.xml` |
+| PHPStan | Level 2 (advisory) | `phpstan.neon` |
+
+PHPStan runs with `--memory-limit=512M`. CI enforces PHPCS errors; PHPStan is `continue-on-error`.
+
+## Rules
+
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
+- **Attribution**: `Authored-by: Moko Consulting`
+- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
+- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
+- **New CLI tools**: extend `CliFramework`, not `CLIApp` (legacy)
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)

.mokogitea/workflows/auto-bump.yml

@@ -7,7 +7,7 @@
 # INGROUP: moko-platform.Release
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /.mokogitea/workflows/auto-bump.yml
-# VERSION: 09.23.00
+# VERSION: 09.02.00
 # BRIEF: Auto patch-bump version on every push to dev (skips merge commits)
 
 name: "Universal: Auto Version Bump"

.mokogitea/workflows/auto-release.yml

@@ -1,285 +1,341 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-#
-# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Release
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
-# PATH: /templates/workflows/universal/auto-release.yml.template
-# VERSION: 05.00.00
-# BRIEF: Universal build & release � detects platform from manifest.xml
-#
-# +========================================================================+
-# |              UNIVERSAL BUILD & RELEASE PIPELINE                        |
-# +========================================================================+
-# |                                                                        |
-# |  Reads manifest.xml (joomla|dolibarr|generic) to branch logic.       |
-# |                                                                        |
-# |  Platform-specific:                                                    |
-# |    joomla:   XML manifest, updates.xml, type-prefixed packages         |
-# |    dolibarr: mod*.class.php, update.txt, dev version reset             |
-# |    generic:  README-only, no update stream                             |
-# |                                                                        |
-# +========================================================================+
-
-name: "Universal: Build & Release"
-
-on:
-  pull_request:
-    types: [opened, closed]
-    branches:
-      - main
-  workflow_dispatch:
-    inputs:
-      action:
-        description: 'Action to perform'
-        required: false
-        type: choice
-        default: release
-        options:
-          - release
-          - promote-rc
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
-  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
-  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
-
-permissions:
-  contents: write
-
-jobs:
-  # ── PR Opened → Rename branch to RC and build RC release ─────────────────────
-  promote-rc:
-    name: Promote to RC
-    runs-on: release
-    if: >-
-      (github.event.action == 'opened' && github.event.pull_request.merged != true) ||
-      (github.event_name == 'workflow_dispatch' && inputs.action == 'promote-rc')
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-        with:
-          token: ${{ secrets.MOKOGITEA_TOKEN }}
-          fetch-depth: 1
-
-      - name: Setup moko-platform tools
-        env:
-          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
-          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-        run: |
-          if ! command -v composer &> /dev/null; then
-            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer >/dev/null 2>&1
-          fi
-          # Always fetch latest CLI tools — never use stale cache from previous runs
-          rm -rf /tmp/moko-platform-api
-          git clone --depth 1 --branch main --quiet \
-            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
-            /tmp/moko-platform-api
-          cd /tmp/moko-platform-api
-          composer install --no-dev --no-interaction --quiet
-
-      - name: Rename branch to rc
-        run: |
-          php /tmp/moko-platform-api/cli/branch_rename.php \
-            --from "${{ github.event.pull_request.head.ref || 'dev' }}" --to rc \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
-            --api-base "${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}" \
-            --pr "${{ github.event.pull_request.number }}"
-
-      - name: Checkout rc and configure git
-        run: |
-          git fetch origin rc
-          git checkout rc
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
-
-      - name: Publish RC release
-        run: |
-          php /tmp/moko-platform-api/cli/release_publish.php \
-            --path . --stability rc --bump minor --branch rc \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
-            --skip-update-stream
-
-      - name: Summary
-        if: always()
-        run: |
-          echo "## Promoted to Release Candidate" >> $GITHUB_STEP_SUMMARY
-          echo "Branch renamed to rc, minor bump, RC release built (updates.xml managed by Gitea Pages)" >> $GITHUB_STEP_SUMMARY
-
-  # ── Merged PR → Build & Release (or promote RC to stable) ────────────────────
-  release:
-    name: Build & Release Pipeline
-    runs-on: release
-    if: >-
-      github.event.pull_request.merged == true ||
-      (github.event_name == 'workflow_dispatch' && inputs.action != 'promote-rc')
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-        with:
-          token: ${{ secrets.MOKOGITEA_TOKEN }}
-          fetch-depth: 0
-
-      - name: Configure git for bot pushes
-        run: |
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
-
-      - name: Check for merge conflict markers
-        run: |
-          CONFLICTS=$(grep -rn '<<<<<<< \|>>>>>>> \|^=======$' --include='*.php' --include='*.xml' --include='*.css' --include='*.js' --include='*.json' --include='*.md' --include='*.yml' --include='*.yaml' --include='*.ini' --include='*.txt' . 2>/dev/null | grep -v '.git/' || true)
-          if [ -n "$CONFLICTS" ]; then
-            echo "::error::Merge conflict markers found — aborting release"
-            echo "## Release Blocked: Conflict Markers" >> $GITHUB_STEP_SUMMARY
-            echo '```' >> $GITHUB_STEP_SUMMARY
-            echo "$CONFLICTS" >> $GITHUB_STEP_SUMMARY
-            echo '```' >> $GITHUB_STEP_SUMMARY
-            exit 1
-          fi
-          echo "No conflict markers found"
-
-      - name: Setup moko-platform tools
-        env:
-          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
-          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GH_MIRROR_TOKEN }}"}}'
-        run: |
-          # Ensure PHP + Composer are available
-          if ! command -v composer &> /dev/null; then
-            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer >/dev/null 2>&1
-          fi
-          # Always fetch latest CLI tools — never use stale cache from previous runs
-          rm -rf /tmp/moko-platform-api
-          git clone --depth 1 --branch main --quiet \
-            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
-            /tmp/moko-platform-api
-          cd /tmp/moko-platform-api
-          composer install --no-dev --no-interaction --quiet
-
-
-      - name: "Publish stable release"
-        run: |
-          php /tmp/moko-platform-api/cli/release_publish.php \
-            --path . --stability stable --bump minor --branch main \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
-            --skip-update-stream
-
-      # -- STEP 9: Mirror to GitHub (stable only) --------------------------------
-      - name: "Step 9: Mirror release to GitHub"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          secrets.GH_MIRROR_TOKEN != ''
-        continue-on-error: true
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
-          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          php /tmp/moko-platform-api/cli/release_mirror.php \
-            --version "$VERSION" --tag "$RELEASE_TAG" \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
-            --gh-token "${{ secrets.GH_MIRROR_TOKEN }}" --gh-repo "$GH_REPO" \
-            --branch main 2>&1 || true
-          echo "GitHub mirror updated" >> $GITHUB_STEP_SUMMARY
-
-      # -- STEP 10: Sync main branch to GitHub mirror ----------------------------
-      - name: "Step 10: Push main to GitHub mirror"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          secrets.GH_MIRROR_TOKEN != ''
-        continue-on-error: true
-        run: |
-          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
-          GH_ORG=$(echo "$GH_REPO" | cut -d/ -f1)
-          GH_NAME=$(echo "$GH_REPO" | cut -d/ -f2)
-          git remote add github "https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git" 2>/dev/null || \
-            git remote set-url github "https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git"
-          git fetch origin main --depth=1
-          git push github origin/main:refs/heads/main --force 2>/dev/null \
-            && echo "main branch pushed to GitHub mirror" \
-            || echo "WARNING: GitHub mirror push failed"
-
-      - name: "Step 11: Delete rc branch and recreate dev from main"
-        if: steps.version.outputs.skip != 'true'
-        continue-on-error: true
-        run: |
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
-
-          # Delete rc branch (ephemeral — created by promote-rc)
-          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
-            "${API_BASE}/branches/rc" 2>/dev/null \
-            && echo "Deleted rc branch" || echo "rc branch not found"
-
-          # Delete dev branch
-          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
-            "${API_BASE}/branches/dev" 2>/dev/null && echo "Deleted dev branch"
-
-          # Recreate dev from main (now includes version bump + changelog promotion)
-          curl -sf -X POST -H "Authorization: token ${TOKEN}" \
-            -H "Content-Type: application/json" \
-            "${API_BASE}/branches" \
-            -d '{"new_branch_name":"dev","old_branch_name":"main"}' 2>/dev/null && echo "Recreated dev from main"
-
-          echo "Pre-release branches cleaned, dev reset from main" >> $GITHUB_STEP_SUMMARY
-
-      - name: "Step 12: Create version branch from main"
-        if: steps.version.outputs.skip != 'true'
-        continue-on-error: true
-        run: |
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          BRANCH_NAME="version/${VERSION}"
-          MAIN_SHA=$(git rev-parse HEAD)
-
-          # Delete old version branch if it exists (same version re-release)
-          curl -sf -X DELETE -H "Authorization: token ${TOKEN}"             "${API_BASE}/branches/${BRANCH_NAME}" 2>/dev/null && echo "Deleted old ${BRANCH_NAME}"
-
-          # Create version/XX.YY.ZZ from main
-          curl -sf -X POST -H "Authorization: token ${TOKEN}"             -H "Content-Type: application/json"             "${API_BASE}/branches"             -d "{\"new_branch_name\":\"${BRANCH_NAME}\",\"old_branch_name\":\"main\"}" 2>/dev/null             && echo "Created ${BRANCH_NAME} from main (${MAIN_SHA})"             || echo "WARNING: ${BRANCH_NAME} creation failed"
-
-          echo "Version branch created: ${BRANCH_NAME} (${MAIN_SHA})" >> $GITHUB_STEP_SUMMARY
-
-
-
-      # -- Dolibarr post-release: Reset dev version -----------------------------
-      - name: "Post-release: Reset dev version"
-        if: steps.version.outputs.skip != 'true'
-        continue-on-error: true
-        run: |
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          php /tmp/moko-platform-api/cli/version_reset_dev.php \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "${API_BASE}" \
-            --branch dev --path . 2>&1 || true
-
-      # -- Summary --------------------------------------------------------------
-      - name: Pipeline Summary
-        if: always()
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          PLATFORM="${{ steps.platform.outputs.platform }}"
-          if [ "${{ steps.version.outputs.skip }}" = "true" ]; then
-            echo "## Release Skipped" >> $GITHUB_STEP_SUMMARY
-            echo "No VERSION in README.md" >> $GITHUB_STEP_SUMMARY
-          elif [ "${{ steps.check.outputs.already_released }}" = "true" ]; then
-            echo "## Already Released — ${VERSION}" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "## Build & Release Complete (${PLATFORM})" >> $GITHUB_STEP_SUMMARY
-            echo "" >> $GITHUB_STEP_SUMMARY
-            echo "| Step | Result |" >> $GITHUB_STEP_SUMMARY
-            echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
-            echo "| Platform | \`${PLATFORM}\` |" >> $GITHUB_STEP_SUMMARY
-            echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
-            echo "| Branch | \`${{ steps.version.outputs.branch }}\` |" >> $GITHUB_STEP_SUMMARY
-            echo "| Tag | \`${{ steps.version.outputs.tag }}\` |" >> $GITHUB_STEP_SUMMARY
-            echo "| Release | [View](${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/tag/${{ steps.version.outputs.tag }}) |" >> $GITHUB_STEP_SUMMARY
-          fi
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Release
+# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
+# PATH: /templates/workflows/universal/auto-release.yml.template
+# VERSION: 05.00.00
+# BRIEF: Universal build & release � detects platform from manifest.xml
+#
+# +========================================================================+
+# |              UNIVERSAL BUILD & RELEASE PIPELINE                        |
+# +========================================================================+
+# |                                                                        |
+# |  Reads manifest.xml (joomla|dolibarr|generic) to branch logic.       |
+# |                                                                        |
+# |  Platform-specific:                                                    |
+# |    joomla:   XML manifest, type-prefixed packages                      |
+# |    dolibarr: mod*.class.php, update.txt, dev version reset             |
+# |    generic:  README-only, no update stream                             |
+# |                                                                        |
+# +========================================================================+
+
+name: "Universal: Build & Release"
+
+on:
+  pull_request:
+    types: [opened, closed]
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      action:
+        description: 'Action to perform'
+        required: false
+        type: choice
+        default: release
+        options:
+          - release
+          - promote-rc
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
+  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
+
+permissions:
+  contents: write
+
+jobs:
+  # ── PR Opened → Rename branch to RC and build RC release ─────────────────────
+  promote-rc:
+    name: Promote to RC
+    runs-on: release
+    if: >-
+      (github.event.action == 'opened' && github.event.pull_request.merged != true) ||
+      (github.event_name == 'workflow_dispatch' && inputs.action == 'promote-rc')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 1
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+        run: |
+          if [ -f /opt/moko-platform/cli/version_bump.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: Rename branch to rc
+        run: |
+          php ${MOKO_CLI}/branch_rename.php \
+            --from "${{ github.event.pull_request.head.ref || 'dev' }}" --to rc \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
+            --api-base "${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}" \
+            --pr "${{ github.event.pull_request.number }}"
+
+      - name: Checkout rc and configure git
+        run: |
+          git fetch origin rc
+          git checkout rc
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Publish RC release
+        run: |
+          php ${MOKO_CLI}/release_publish.php \
+            --path . --stability rc --bump minor --branch rc \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}"
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Promoted to Release Candidate" >> $GITHUB_STEP_SUMMARY
+          echo "Branch renamed to rc, minor bump, RC release built" >> $GITHUB_STEP_SUMMARY
+
+  # ── Merged PR → Build & Release (or promote RC to stable) ────────────────────
+  release:
+    name: Build & Release Pipeline
+    runs-on: release
+    if: >-
+      github.event.pull_request.merged == true ||
+      (github.event_name == 'workflow_dispatch' && inputs.action != 'promote-rc')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 0
+
+      - name: Configure git for bot pushes
+        run: |
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Check for merge conflict markers
+        run: |
+          CONFLICTS=$(grep -rn '<<<<<<< \|>>>>>>> \|^=======$' --include='*.php' --include='*.xml' --include='*.css' --include='*.js' --include='*.json' --include='*.md' --include='*.yml' --include='*.yaml' --include='*.ini' --include='*.txt' . 2>/dev/null | grep -v '.git/' || true)
+          if [ -n "$CONFLICTS" ]; then
+            echo "::error::Merge conflict markers found — aborting release"
+            echo "## Release Blocked: Conflict Markers" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "$CONFLICTS" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+          echo "No conflict markers found"
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GH_MIRROR_TOKEN }}"}}'
+        run: |
+          if [ -f /opt/moko-platform/cli/version_bump.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: "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_FLAG} --branch main \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}"
+
+      - name: Update release notes from CHANGELOG.md
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+
+          # Extract [Unreleased] section from changelog
+          if [ -f "CHANGELOG.md" ]; then
+            NOTES=$(awk '/^## \[Unreleased\]/{found=1; next} /^## \[/{if(found) exit} found{print}' CHANGELOG.md)
+            [ -z "$NOTES" ] && NOTES="Stable release"
+          else
+            NOTES="Stable release"
+          fi
+
+          # Update release body via API
+          RELEASE_ID=$(curl -sf -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \
+            "${API_BASE}/releases/tags/stable" | 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
+
+      # -- STEP 9: Mirror to GitHub (stable only) --------------------------------
+      - name: "Step 9: Mirror release to GitHub"
+        if: >-
+          steps.version.outputs.skip != 'true' &&
+          secrets.GH_MIRROR_TOKEN != ''
+        continue-on-error: true
+        run: |
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
+          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php ${MOKO_CLI}/release_mirror.php \
+            --version "$VERSION" --tag "$RELEASE_TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --gh-token "${{ secrets.GH_MIRROR_TOKEN }}" --gh-repo "$GH_REPO" \
+            --branch main 2>&1 || true
+          echo "GitHub mirror updated" >> $GITHUB_STEP_SUMMARY
+
+      # -- STEP 10: Sync main branch to GitHub mirror ----------------------------
+      - name: "Step 10: Push main to GitHub mirror"
+        if: >-
+          steps.version.outputs.skip != 'true' &&
+          secrets.GH_MIRROR_TOKEN != ''
+        continue-on-error: true
+        run: |
+          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
+          GH_ORG=$(echo "$GH_REPO" | cut -d/ -f1)
+          GH_NAME=$(echo "$GH_REPO" | cut -d/ -f2)
+          git remote add github "https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git" 2>/dev/null || \
+            git remote set-url github "https://x-access-token:${{ secrets.GH_MIRROR_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git"
+          git fetch origin main --depth=1
+          git push github origin/main:refs/heads/main --force 2>/dev/null \
+            && echo "main branch pushed to GitHub mirror" \
+            || echo "WARNING: GitHub mirror push failed"
+
+      - name: "Step 11: Delete rc branch and recreate dev from main"
+        if: steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
+
+          # Delete rc branch (ephemeral — created by promote-rc)
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/branches/rc" 2>/dev/null \
+            && echo "Deleted rc branch" || echo "rc branch not found"
+
+          # Delete dev branch
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/branches/dev" 2>/dev/null && echo "Deleted dev branch"
+
+          # Recreate dev from main (now includes version bump + changelog promotion)
+          curl -sf -X POST -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${API_BASE}/branches" \
+            -d '{"new_branch_name":"dev","old_branch_name":"main"}' 2>/dev/null && echo "Recreated dev from main"
+
+          echo "Pre-release branches cleaned, dev reset from main" >> $GITHUB_STEP_SUMMARY
+
+      - name: "Step 12: Create version branch from main"
+        if: steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          BRANCH_NAME="version/${VERSION}"
+          MAIN_SHA=$(git rev-parse HEAD)
+
+          # Delete old version branch if it exists (same version re-release)
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}"             "${API_BASE}/branches/${BRANCH_NAME}" 2>/dev/null && echo "Deleted old ${BRANCH_NAME}"
+
+          # Create version/XX.YY.ZZ from main
+          curl -sf -X POST -H "Authorization: token ${TOKEN}"             -H "Content-Type: application/json"             "${API_BASE}/branches"             -d "{\"new_branch_name\":\"${BRANCH_NAME}\",\"old_branch_name\":\"main\"}" 2>/dev/null             && echo "Created ${BRANCH_NAME} from main (${MAIN_SHA})"             || echo "WARNING: ${BRANCH_NAME} creation failed"
+
+          echo "Version branch created: ${BRANCH_NAME} (${MAIN_SHA})" >> $GITHUB_STEP_SUMMARY
+
+
+
+      # -- Dolibarr post-release: Reset dev version -----------------------------
+      - name: "Post-release: Reset dev version"
+        if: steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php ${MOKO_CLI}/version_reset_dev.php \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "${API_BASE}" \
+            --branch dev --path . 2>&1 || true
+
+      # -- Summary --------------------------------------------------------------
+      - name: Pipeline Summary
+        if: always()
+        run: |
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          if [ "${{ steps.version.outputs.skip }}" = "true" ]; then
+            echo "## Release Skipped" >> $GITHUB_STEP_SUMMARY
+            echo "No VERSION in README.md" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ steps.check.outputs.already_released }}" = "true" ]; then
+            echo "## Already Released — ${VERSION}" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "## Build & Release Complete (${PLATFORM})" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "| Step | Result |" >> $GITHUB_STEP_SUMMARY
+            echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
+            echo "| Platform | \`${PLATFORM}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Branch | \`${{ steps.version.outputs.branch }}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Tag | \`${{ steps.version.outputs.tag }}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Release | [View](${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/tag/${{ steps.version.outputs.tag }}) |" >> $GITHUB_STEP_SUMMARY
+          fi

.mokogitea/workflows/branch-cleanup.yml

@@ -4,10 +4,10 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoPlatform.Universal
+# INGROUP: MokoStandards.Universal
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /.mokogitea/workflows/branch-cleanup.yml
-# VERSION: 09.23.00
+# VERSION: 01.00.00
 # BRIEF: Delete feature branches after PR merge
 
 name: "Branch Cleanup"

.mokogitea/workflows/ci-generic.yml

@@ -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

.mokogitea/workflows/ci-platform.yml

@@ -6,7 +6,7 @@
 # DEFGROUP: Gitea.Workflow
 # INGROUP: moko-platform.CI
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
-# PATH: /.gitea/workflows/ci-platform.yml
+# PATH: /.mokogitea/workflows/ci-platform.yml
 # VERSION: 09.23.00
 # BRIEF: moko-platform CI — the standards engine validates itself
 #
@@ -41,7 +41,7 @@ on:
     paths-ignore:
       - '**.md'
       - 'wiki/**'
-      - '.gitea/ISSUE_TEMPLATE/**'
+      - '.mokogitea/ISSUE_TEMPLATE/**'
   pull_request:
     branches:
       - main
@@ -104,7 +104,7 @@ jobs:
               echo "::error file=${file}::PHP syntax error"
               ERRORS=$((ERRORS + 1))
             fi
-          done < <(find lib/ validate/ automation/ cli/ src/ deploy/ -name "*.php" -print0 2>/dev/null)
+          done < <(find lib/ validate/ automation/ cli/ source/ src/ deploy/ -name "*.php" -print0 2>/dev/null)
 
           {
             echo "### PHP Syntax"
@@ -270,7 +270,7 @@ jobs:
               echo "::warning file=${file}::Missing SPDX header"
               MISSING=$((MISSING + 1))
             fi
-          done < <(find lib/ validate/ cli/ src/ automation/ deploy/ -name "*.php" -print0 2>/dev/null)
+          done < <(find lib/ validate/ cli/ source/ src/ automation/ deploy/ -name "*.php" -print0 2>/dev/null)
 
           {
             echo "### License Headers"
@@ -289,7 +289,7 @@ jobs:
               echo "::error file=${file}::Potential hardcoded secret detected"
               FOUND=$((FOUND + 1))
             fi
-          done < <(find lib/ validate/ cli/ src/ automation/ deploy/ -name "*.php" -print0 2>/dev/null)
+          done < <(find lib/ validate/ cli/ source/ src/ automation/ deploy/ -name "*.php" -print0 2>/dev/null)
 
           {
             echo "### Secret Detection"

.mokogitea/workflows/cleanup.yml

@@ -4,10 +4,10 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Maintenance
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# INGROUP: MokoStandards.Maintenance
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
 # PATH: /.gitea/workflows/cleanup.yml
-# VERSION: 09.23.00
+# VERSION: 01.00.00
 # BRIEF: Scheduled cleanup — delete merged branches and old workflow runs
 
 name: "Universal: Repository Cleanup"
@@ -33,17 +33,17 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          token: ${{ secrets.GA_TOKEN }}
 
       - name: Delete merged branches
         env:
-          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          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 ${GITEA_TOKEN}" \
+          BRANCHES=$(curl -sS -H "Authorization: token ${GA_TOKEN}" \
             "${API}/branches?limit=50" | jq -r '.[].name')
 
           DELETED=0
@@ -56,7 +56,7 @@ jobs:
             # 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 ${GITEA_TOKEN}" \
+              curl -sS -X DELETE -H "Authorization: token ${GA_TOKEN}" \
                 "${API}/branches/${BRANCH}" 2>/dev/null || true
               DELETED=$((DELETED + 1))
             fi
@@ -66,20 +66,20 @@ jobs:
 
       - name: Clean old workflow runs
         env:
-          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          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 ${GITEA_TOKEN}" \
+          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 ${GITEA_TOKEN}" \
+            curl -sS -X DELETE -H "Authorization: token ${GA_TOKEN}" \
               "${API}/actions/runs/${RUN_ID}" 2>/dev/null || true
             DELETED=$((DELETED + 1))
           done

.mokogitea/workflows/deploy-manual.yml

@@ -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

.mokogitea/workflows/gitleaks.yml

@@ -4,10 +4,10 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Security
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
+# INGROUP: MokoStandards.Security
+# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
 # PATH: /templates/workflows/gitleaks.yml.template
-# VERSION: 09.23.00
+# VERSION: 01.00.00
 # BRIEF: Secret scanning — detect leaked credentials, API keys, and tokens
 #
 # +========================================================================+

.mokogitea/workflows/issue-branch.yml

@@ -5,7 +5,7 @@
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
 # INGROUP: moko-platform.Automation
-# VERSION: 09.25.00
+# VERSION: 01.00.00
 # BRIEF: Auto-create feature branch when an issue is opened
 
 name: "Universal: Issue Branch"
@@ -28,7 +28,7 @@ jobs:
     steps:
       - name: Create branch and comment
         run: |
-          TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"
+          TOKEN="${{ secrets.GA_TOKEN }}"
           API="${GITEA_URL}/api/v1/repos/${{ github.repository }}"
           ISSUE_NUM="${{ github.event.issue.number }}"
           ISSUE_TITLE="${{ github.event.issue.title }}"

.mokogitea/workflows/notify.yml

@@ -4,10 +4,10 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Notifications
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# INGROUP: MokoStandards.Notifications
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
 # PATH: /.gitea/workflows/notify.yml
-# VERSION: 09.23.00
+# VERSION: 01.00.00
 # BRIEF: Push notifications via ntfy on release success or workflow failure
 
 name: "Universal: Notifications"

.mokogitea/workflows/pre-release.yml

@@ -7,178 +7,5 @@
 # INGROUP: moko-platform.Release
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /templates/workflows/universal/pre-release.yml.template
-# VERSION: 09.23.00
-# BRIEF: Manual pre-release -- builds dev/alpha/beta/rc packages from any branch
-
-name: "Universal: Pre-Release"
-
-on:
-  pull_request:
-    types: [closed]
-    branches:
-      - dev
-  workflow_dispatch:
-    inputs:
-      stability:
-        description: 'Pre-release channel'
-        required: true
-        type: choice
-        options:
-          - development
-          - alpha
-          - beta
-          - release-candidate
-
-permissions:
-  contents: write
-
-env:
-  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
-  GITEA_ORG: ${{ vars.GITEA_ORG || github.repository_owner }}
-  GITEA_REPO: ${{ vars.GITEA_REPO || github.event.repository.name }}
-
-jobs:
-  build:
-    name: "Build Pre-Release (${{ inputs.stability || 'development' }})"
-    runs-on: release
-    if: >-
-      github.event_name == 'workflow_dispatch' ||
-      (github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev')
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.MOKOGITEA_TOKEN }}
-
-      - name: Setup moko-platform tools
-        env:
-          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
-          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-        run: |
-          if ! command -v composer &> /dev/null; then
-            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer >/dev/null 2>&1
-          fi
-          # Always fetch latest CLI tools — never use stale cache from previous runs
-          rm -rf /tmp/moko-platform-api
-          git clone --depth 1 --branch main --quiet \
-            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
-            /tmp/moko-platform-api
-          cd /tmp/moko-platform-api && composer install --no-dev --no-interaction --quiet
-          echo "MOKO_CLI=/tmp/moko-platform-api/cli" >> "$GITHUB_ENV"
-
-      - name: Detect platform
-        id: platform
-        run: |
-          php ${MOKO_CLI}/manifest_read.php --path . --github-output
-
-      - name: Resolve metadata and bump version
-        id: meta
-        run: |
-          STABILITY="${{ inputs.stability || 'development' }}"
-
-          case "$STABILITY" in
-            development)        TAG="development" ;;
-            alpha)              TAG="alpha" ;;
-            beta)               TAG="beta" ;;
-            release-candidate)  TAG="release-candidate" ;;
-          esac
-
-          # Bump version: patch for dev/alpha/beta, minor for RC
-          case "$STABILITY" in
-            release-candidate) php ${MOKO_CLI}/version_bump.php --path . --minor 2>/dev/null || true ;;
-            *)                 php ${MOKO_CLI}/version_bump.php --path . 2>/dev/null || true ;;
-          esac
-
-          # Set stability suffix and fix 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
-
-          # Read final version with suffix
-          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null)
-          [ -z "$VERSION" ] && VERSION="00.00.01"
-
-          # Commit version bump
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          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 "tag=${TAG}" >> "$GITHUB_OUTPUT"
-          echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
-          echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"
-
-          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION} ==="
-
-      - name: Create release
-        id: release
-        run: |
-          TAG="${{ steps.meta.outputs.tag }}"
-          VERSION="${{ steps.meta.outputs.version }}"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          php ${MOKO_CLI}/release_create.php \
-            --path . --version "$VERSION" --tag "$TAG" \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
-            --repo "${GITEA_REPO}" --branch dev --prerelease
-
-      - name: Build package and upload
-        id: package
-        run: |
-          VERSION="${{ steps.meta.outputs.version }}"
-          TAG="${{ steps.meta.outputs.tag }}"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          php ${MOKO_CLI}/release_package.php \
-            --path . --version "$VERSION" --tag "$TAG" \
-            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
-            --repo "${GITEA_REPO}" --output /tmp || true
-
-      # 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
+# VERSION: 05.01.00
+# BRIEF: Auto pre-release on push to dev/alpha/beta/rc branches

.mokogitea/workflows/security-audit.yml

@@ -4,10 +4,10 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: moko-platform.Security
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# INGROUP: MokoStandards.Security
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
 # PATH: /.gitea/workflows/security-audit.yml
-# VERSION: 09.23.00
+# VERSION: 01.00.00
 # BRIEF: Dependency vulnerability scanning for composer and npm packages
 
 name: "Universal: Security Audit"
@@ -80,19 +80,3 @@ jobs:
             -H "Priority: high" \
             -d "Security audit found vulnerabilities. Review dependency updates." \
             "${NTFY_URL}/${NTFY_TOPIC}" || true
-
-
-      - name: Joomla version audit
-        if: always()
-        run: |
-          if [ -f "monitoring/joomla-version-audit.php" ] && [ -n "$JOOMLA_SITES" ]; then
-            echo "$JOOMLA_SITES" > /tmp/sites.json
-            php monitoring/joomla-version-audit.php --sites /tmp/sites.json || true
-            echo "### Joomla Version Audit" >> $GITHUB_STEP_SUMMARY
-            rm -f /tmp/sites.json
-          else
-            echo "Joomla audit skipped (no script or JOOMLA_SITES_JSON not configured)"
-          fi
-        env:
-          JOOMLA_SITES: ${{ vars.JOOMLA_SITES_JSON }}
-

.mokogitea/workflows/update-server.yml

@@ -1,302 +0,0 @@
-# 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: 09.23.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"
-
-          # 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
-
-          # Gitea release tag per stability
-          case "$STABILITY" in
-            development) TAG="development" ;;
-            alpha)       TAG="alpha" ;;
-            beta)        TAG="beta" ;;
-            rc)          TAG="release-candidate" ;;
-            *)           TAG="stable" ;;
-          esac
-
-          # Bump patch, set platform suffix, fix consistency — version_bump preserves suffix
-          php ${MOKO_CLI}/version_set_platform.php \
-            --path . --version "$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo '00.00.01')" \
-            --branch "$BRANCH" --stability "$STABILITY" 2>/dev/null || true
-          php ${MOKO_CLI}/version_bump.php --path . 2>/dev/null || true
-          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
-
-          # Read final version (includes suffix, e.g. 01.02.15-dev)
-          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "00.00.01")
-
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
-          echo "tag=${TAG}" >> "$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="${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

CHANGELOG.md

@@ -12,6 +12,17 @@ BRIEF: Release changelog
 # Changelog
 ## [Unreleased]
 
+### Added
+- `workflow_sync.php` — cascading workflow sync from Generic → platform templates → live repos based on manifest.platform
+- `platform_detect.php` — auto-detect repo platform type (joomla/dolibarr/go/mcp/platform/generic) from file structure, optionally update manifest
+- Version prefix support in `version_read.php` and `version_bump.php` — repos with `<version_prefix>` in manifest (e.g. MokoGitea: `1.26.1+moko.`) get prefix-aware version scanning and bumping
+- Platform types: joomla, dolibarr, go, mcp, platform, generic
+- Template-Go and Template-MCP repos created
+
+### Changed
+- `auto-release.yml` — patch branches (fix/*, patch/*, hotfix/*, bugfix/*) use `--bump none` (pre-release already bumped); feature/dev branches bump minor
+- `pre-release.yml` — triggers on push to dev, fix/**, patch/**, hotfix/**, bugfix/**, alpha, beta, rc branches
+- Version format standardized: `[prefix]XX.YY.ZZ` in source files, suffix (`-dev`, `-rc`) added by release system only
 
 ## [09.25.00] --- 2026-06-04
 

CLAUDE.md

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

README.md

@@ -6,7 +6,7 @@ DEFGROUP: MokoPlatform.Root
 INGROUP: MokoPlatform
 REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 PATH: /README.md
-VERSION: 09.25.00
+VERSION: 09.25.02
 BRIEF: Project overview and documentation
 -->
 

cli/branch_rename.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/branch_rename.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Rename a git branch via Gitea API (create new, update PR, delete old)
  */
 

cli/bulk_workflow_push.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/bulk_workflow_push.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Push a workflow file to all governed repos via the Gitea Contents API
  */
 

cli/bulk_workflow_trigger.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/bulk_workflow_trigger.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Trigger a workflow across multiple repos at once
  */
 

cli/client_dashboard.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/client_dashboard.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Generate unified client dashboard HTML
  */
 

cli/client_inventory.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/client_inventory.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Discover and list all client-waas repos with their server configuration status
  */
 

cli/client_provision.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/client_provision.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Provision a new client environment end-to-end
  */
 

cli/deploy_joomla.php

@@ -31,7 +31,7 @@ require_once __DIR__ . '/../vendor/autoload.php';
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 use phpseclib3\Net\SFTP;
 use phpseclib3\Crypt\PublicKeyLoader;
 
@@ -866,11 +866,11 @@ class DeployJoomla extends CliFramework
             }
         }
 
-        // 3-5. Fallback chain
-        foreach (['src', 'htdocs'] as $candidate) {
-            if (is_dir("{$repoPath}/{$candidate}")) {
-                return "{$repoPath}/{$candidate}";
-            }
+        // 3-5. Fallback chain (source/ → src/ → htdocs/)
+        $resolved = SourceResolver::resolveAbsolute($repoPath);
+        if ($resolved !== null) {
+            SourceResolver::warnIfLegacy($repoPath);
+            return $resolved;
         }
 
         // Last resort: repo root itself

cli/grafana_dashboard.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/grafana_dashboard.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Manage Grafana dashboards via API
  */
 

cli/joomla_build.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/joomla_build.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Build a Joomla extension ZIP from manifest — all types supported
  * NOTE: Called by pre-release and auto-release workflows.
  */
@@ -19,7 +19,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class JoomlaBuildCli extends CliFramework
 {
@@ -49,17 +49,12 @@ class JoomlaBuildCli extends CliFramework
         $path = realpath($path) ?: $path;
 
         // ── Find source directory ──────────────────────────────────────────────
-        $srcDir = null;
-        foreach (['src', 'htdocs'] as $d) {
-            if (is_dir("{$path}/{$d}")) {
-                $srcDir = "{$path}/{$d}";
-                break;
-            }
-        }
+        $srcDir = SourceResolver::resolveAbsolute($path);
         if ($srcDir === null) {
-            $this->log('ERROR', "::error::No src/ or htdocs/ directory in {$path}");
+            $this->log('ERROR', "::error::No source/ or src/ directory in {$path}");
             return 1;
         }
+        SourceResolver::warnIfLegacy($path);
 
         // ── Find manifest ──────────────────────────────────────────────────────
         $manifest = $this->findManifest($srcDir);

cli/joomla_release.php

@@ -25,7 +25,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-use MokoEnterprise\{ApiClient, AuditLogger, CliFramework, Config, PlatformAdapterFactory};
+use MokoEnterprise\{ApiClient, AuditLogger, CliFramework, Config, PlatformAdapterFactory, SourceResolver};
 
 /**
  * Joomla Release Manager
@@ -121,11 +121,12 @@ class JoomlaRelease extends CliFramework
         $this->log('INFO', "Version: {$displayVersion}  |  Release tag: {$releaseTag}");
 
         // ── Step 3: Build packages ────────────────────────────────────
-        $srcDir = is_dir("{$path}/src") ? "{$path}/src" : (is_dir("{$path}/htdocs") ? "{$path}/htdocs" : null);
+        $srcDir = SourceResolver::resolveAbsolute($path);
         if ($srcDir === null) {
-            $this->log('ERROR', 'No src/ or htdocs/ directory');
+            $this->log('ERROR', 'No source/ or src/ directory');
             return 1;
         }
+        SourceResolver::warnIfLegacy($path);
 
         $prefix  = $this->typePrefix($meta);
         $zipName = "{$prefix}{$meta['element']}-{$displayVersion}.zip";

cli/manifest_element.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class ManifestElementCli extends CliFramework
 {
@@ -48,7 +48,7 @@ class ManifestElementCli extends CliFramework
             }
         }
         $extManifest = null;
-        $manifestFiles = array_merge(glob("{$root}/src/pkg_*.xml") ?: [], glob("{$root}/src/*.xml") ?: [], glob("{$root}/*.xml") ?: []);
+        $manifestFiles = array_merge(SourceResolver::globSource($root, 'pkg_*.xml'), SourceResolver::globSource($root, '*.xml'), glob("{$root}/*.xml") ?: []);
         foreach ($manifestFiles as $file) {
             $c = file_get_contents($file);
             if (strpos($c, '<extension') !== false) {
@@ -58,8 +58,7 @@ class ManifestElementCli extends CliFramework
         }
         $modFile = null;
         $modFiles = array_merge(
-            glob("{$root}/src/core/modules/mod*.class.php") ?: [],
-            glob("{$root}/htdocs/core/modules/mod*.class.php") ?: [],
+            SourceResolver::globSource($root, 'core/modules/mod*.class.php'),
             glob("{$root}/core/modules/mod*.class.php") ?: []
         );
         foreach ($modFiles as $file) {

cli/manifest_licensing.php

@@ -0,0 +1,280 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/manifest_licensing.php
+ * VERSION: 09.25.02
+ * BRIEF: Ensure licensing tags (updateservers, dlid) in Joomla extension manifests
+ */
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
+
+use MokoEnterprise\{CliFramework, SourceResolver};
+
+/**
+ * Reads the <licensing> block from .mokogitea/manifest.xml and ensures that the
+ * Joomla extension manifest contains the correct <updateservers> and <dlid> tags.
+ *
+ * manifest.xml licensing block example:
+ *
+ *   <licensing>
+ *     <enabled>true</enabled>
+ *     <dlid>true</dlid>
+ *     <update-server>https://git.mokoconsulting.tech/{org}/{repo}/updates.xml</update-server>
+ *     <update-server-name>MyExtension Updates</update-server-name>
+ *   </licensing>
+ *
+ * Supports {org} and {repo} placeholders in update-server URL, resolved from
+ * the manifest's <identity> block or git remote.
+ */
+class ManifestLicensingCli extends CliFramework
+{
+    protected function configure(): void
+    {
+        $this->setDescription('Ensure licensing tags (updateservers, dlid) in Joomla extension manifests');
+        $this->addArgument('--path', 'Repository root path', '.');
+        $this->addArgument('--fix', 'Apply fixes (default: dry-run check only)', false);
+        $this->addArgument('--github-output', 'Write results to $GITHUB_OUTPUT', false);
+    }
+
+    protected function run(): int
+    {
+        $root     = realpath($this->getArgument('--path')) ?: $this->getArgument('--path');
+        $fix      = (bool) $this->getArgument('--fix');
+        $ghOutput = (bool) $this->getArgument('--github-output');
+
+        // ── 1. Read manifest.xml ──────────────────────────────────────────
+        $manifestFile = "{$root}/.mokogitea/manifest.xml";
+
+        if (!file_exists($manifestFile)) {
+            $this->log('WARN', "No manifest.xml found at {$manifestFile}");
+            $this->outputResult($ghOutput, 'skipped', 'No manifest.xml');
+            return 0;
+        }
+
+        $xml = @simplexml_load_file($manifestFile);
+
+        if ($xml === false) {
+            $this->log('ERROR', "Failed to parse {$manifestFile}");
+            return 1;
+        }
+
+        // ── 2. Check if licensing is enabled ──────────────────────────────
+        if (!isset($xml->licensing) || (string) ($xml->licensing->enabled ?? '') !== 'true') {
+            $this->log('INFO', 'Licensing not enabled in manifest.xml — skipping');
+            $this->outputResult($ghOutput, 'skipped', 'Licensing not enabled');
+            return 0;
+        }
+
+        $licensingNode    = $xml->licensing;
+        $dlidEnabled      = ((string) ($licensingNode->dlid ?? 'true')) === 'true';
+        $updateServerUrl  = (string) ($licensingNode->{'update-server'} ?? '');
+        $updateServerName = (string) ($licensingNode->{'update-server-name'} ?? '');
+
+        // ── 3. Resolve placeholders ───────────────────────────────────────
+        $org  = (string) ($xml->identity->org ?? '');
+        $repo = (string) ($xml->identity->name ?? '');
+
+        // Fallback to git remote if manifest doesn't have org/name
+        if (empty($org) || empty($repo)) {
+            $remote = trim((string) @shell_exec("cd " . escapeshellarg($root) . " && git remote get-url origin 2>/dev/null"));
+
+            if (preg_match('#[/:]([^/]+)/([^/.]+?)(?:\.git)?$#', $remote, $m)) {
+                if (empty($org)) {
+                    $org = $m[1];
+                }
+                if (empty($repo)) {
+                    $repo = $m[2];
+                }
+            }
+        }
+
+        // Default update server URL if not specified
+        if (empty($updateServerUrl) && !empty($org) && !empty($repo)) {
+            $updateServerUrl = "https://git.mokoconsulting.tech/{$org}/{$repo}/updates.xml";
+        }
+
+        // Resolve {org} and {repo} placeholders
+        $updateServerUrl = str_replace(['{org}', '{repo}'], [$org, $repo], $updateServerUrl);
+
+        // Default server name from display-name or repo name
+        if (empty($updateServerName)) {
+            $displayName = (string) ($xml->identity->{'display-name'} ?? $repo);
+            $updateServerName = $displayName . ' Updates';
+        }
+
+        if (empty($updateServerUrl)) {
+            $this->log('ERROR', 'Cannot determine update server URL — set <update-server> in manifest.xml or ensure org/repo are available');
+            return 1;
+        }
+
+        $this->log('INFO', "Licensing enabled — org={$org}, repo={$repo}");
+        $this->log('INFO', "Update server: {$updateServerUrl}");
+        $this->log('INFO', "DLID required: " . ($dlidEnabled ? 'yes' : 'no'));
+
+        // ── 4. Find Joomla extension manifests ────────────────────────────
+        $xmlFiles = array_merge(
+            SourceResolver::globSource($root, '*.xml'),
+            SourceResolver::globSource($root, 'packages/*/*.xml'),
+            glob("{$root}/*.xml") ?: []
+        );
+
+        $packageManifest = null;
+
+        foreach ($xmlFiles as $file) {
+            $content = file_get_contents($file);
+
+            if (!str_contains($content, '<extension')) {
+                continue;
+            }
+
+            // Find the package manifest (type="package") or the main extension manifest
+            if (str_contains($content, 'type="package"')) {
+                $packageManifest = $file;
+                break;
+            }
+
+            // Fallback: first extension manifest found
+            if ($packageManifest === null) {
+                $packageManifest = $file;
+            }
+        }
+
+        if ($packageManifest === null) {
+            $this->log('WARN', 'No Joomla extension manifest found');
+            $this->outputResult($ghOutput, 'skipped', 'No extension manifest');
+            return 0;
+        }
+
+        $relPath = str_replace($root . '/', '', str_replace('\\', '/', $packageManifest));
+        $this->log('INFO', "Package manifest: {$relPath}");
+
+        // ── 5. Check and fix the manifest ─────────────────────────────────
+        $content  = file_get_contents($packageManifest);
+        $original = $content;
+        $changes  = [];
+
+        // --- 5a. Ensure <updateservers> block with correct URL ---
+        if (preg_match('#<updateservers>\s*</updateservers>#s', $content)) {
+            // Empty updateservers block — inject the server
+            $replacement = "<updateservers>\n"
+                . "        <server type=\"extension\" name=\"{$updateServerName}\">{$updateServerUrl}</server>\n"
+                . "    </updateservers>";
+            $content = preg_replace('#<updateservers>\s*</updateservers>#s', $replacement, $content);
+            $changes[] = 'Added update server URL to empty <updateservers>';
+        } elseif (!str_contains($content, '<updateservers>')) {
+            // No updateservers at all — add before </extension>
+            $serverBlock = "\n    <updateservers>\n"
+                . "        <server type=\"extension\" name=\"{$updateServerName}\">{$updateServerUrl}</server>\n"
+                . "    </updateservers>\n";
+            $content = str_replace('</extension>', $serverBlock . '</extension>', $content);
+            $changes[] = 'Added <updateservers> block';
+        } else {
+            // updateservers exists — verify URL is correct
+            if (preg_match('#<server[^>]*>([^<]+)</server>#', $content, $m)) {
+                if ($m[1] !== $updateServerUrl) {
+                    $content = preg_replace(
+                        '#(<server[^>]*>)[^<]+(</server>)#',
+                        "\${1}{$updateServerUrl}\${2}",
+                        $content
+                    );
+                    $changes[] = "Updated server URL: {$m[1]} → {$updateServerUrl}";
+                }
+            }
+        }
+
+        // --- 5b. Ensure <dlid> tag if required ---
+        if ($dlidEnabled) {
+            if (!str_contains($content, '<dlid')) {
+                // Add before <updateservers> if present, otherwise before </extension>
+                $dlidTag = '    <dlid prefix="dlid=" suffix=""/>' . "\n";
+
+                if (str_contains($content, '<updateservers>')) {
+                    $content = str_replace('<updateservers>', $dlidTag . "\n    <updateservers>", $content);
+                } else {
+                    $content = str_replace('</extension>', $dlidTag . '</extension>', $content);
+                }
+
+                $changes[] = 'Added <dlid> tag';
+            }
+        }
+
+        // --- 5c. Ensure <blockChildUninstall> for packages ---
+        if (str_contains($content, 'type="package"') && !str_contains($content, '<blockChildUninstall>')) {
+            $blockTag = '    <blockChildUninstall>true</blockChildUninstall>' . "\n";
+
+            if (str_contains($content, '<dlid')) {
+                // Add after <dlid>
+                $content = preg_replace(
+                    '#(<dlid[^/]*/>\s*\n)#',
+                    "\${1}{$blockTag}",
+                    $content
+                );
+            } elseif (str_contains($content, '<updateservers>')) {
+                $content = str_replace('<updateservers>', $blockTag . "\n    <updateservers>", $content);
+            } else {
+                $content = str_replace('</extension>', $blockTag . '</extension>', $content);
+            }
+
+            $changes[] = 'Added <blockChildUninstall>true</blockChildUninstall>';
+        }
+
+        // ── 6. Report and apply ───────────────────────────────────────────
+        if (empty($changes)) {
+            $this->log('INFO', 'All licensing tags are correct — no changes needed');
+            $this->outputResult($ghOutput, 'ok', 'No changes needed');
+            return 0;
+        }
+
+        foreach ($changes as $change) {
+            $this->log($fix ? 'INFO' : 'WARN', ($fix ? 'Fixed: ' : 'Needs fix: ') . $change);
+        }
+
+        if ($fix) {
+            file_put_contents($packageManifest, $content);
+            $this->log('INFO', "Wrote {$relPath} with " . count($changes) . " change(s)");
+            $this->outputResult($ghOutput, 'fixed', implode('; ', $changes));
+        } else {
+            $this->log('WARN', 'Run with --fix to apply changes');
+            $this->outputResult($ghOutput, 'needs-fix', implode('; ', $changes));
+            return 1;
+        }
+
+        return 0;
+    }
+
+    /**
+     * Write result to $GITHUB_OUTPUT if requested.
+     */
+    private function outputResult(bool $ghOutput, string $status, string $detail): void
+    {
+        if (!$ghOutput) {
+            return;
+        }
+
+        $outputFile = getenv('GITHUB_OUTPUT');
+
+        if ($outputFile === false || $outputFile === '') {
+            echo "licensing_status={$status}\n";
+            echo "licensing_detail={$detail}\n";
+            return;
+        }
+
+        $fh = fopen($outputFile, 'a');
+        fwrite($fh, "licensing_status={$status}\n");
+        fwrite($fh, "licensing_detail={$detail}\n");
+        fclose($fh);
+    }
+}
+
+$app = new ManifestLicensingCli();
+exit($app->execute());

cli/manifest_read.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/manifest_read.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Parse .manifest.xml and output requested field(s) for CI consumption
  */
 

cli/package_build.php

@@ -19,7 +19,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class PackageBuildCli extends CliFramework
 {
@@ -56,18 +56,13 @@ class PackageBuildCli extends CliFramework
         }
 
         // -- Determine source directory -----------------------------------------------
-        $sourceDir = null;
-        foreach (['src', 'htdocs'] as $candidate) {
-            if (is_dir("{$root}/{$candidate}")) {
-                $sourceDir = "{$root}/{$candidate}";
-                break;
-            }
-        }
+        $sourceDir = SourceResolver::resolveAbsolute($root);
 
         if ($sourceDir === null) {
-            $this->log('ERROR', "No src/ or htdocs/ directory found in {$root}");
+            $this->log('ERROR', "No source/ or src/ directory found in {$root}");
             return 1;
         }
+        SourceResolver::warnIfLegacy($root);
 
         // -- Determine element and type prefix from manifest --------------------------
         $extElement = $elementOverride;

cli/platform_detect.php

@@ -10,7 +10,8 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/platform_detect.php
- * BRIEF: Detect platform from manifest.xml file — outputs platform string
+ * VERSION: 09.25.02
+ * BRIEF: Auto-detect repository platform type and optionally update manifest
  */
 
 declare(strict_types=1);
@@ -23,8 +24,14 @@ class PlatformDetectCli extends CliFramework
 {
     protected function configure(): void
     {
-        $this->setDescription('Detect platform from manifest.xml file');
-        $this->addArgument('--path', 'Repository root path', '.');
+        $this->setDescription('Auto-detect repository platform type and optionally update manifest');
+        $this->addArgument('--path', 'Local repo path to scan (default: .)', '.');
+        $this->addArgument('--token', 'Gitea API token for updating manifest', '');
+        $this->addArgument('--gitea-url', 'Gitea URL (default: https://git.mokoconsulting.tech)', 'https://git.mokoconsulting.tech');
+        $this->addArgument('--owner', 'Repo owner for API update', '');
+        $this->addArgument('--repo', 'Repo name for API update', '');
+        $this->addArgument('--update', 'Update manifest.platform via API (flag)', 'false');
+        $this->addArgument('--github-output', 'Append platform=xxx to $GITHUB_OUTPUT (flag)', 'false');
     }
 
     protected function run(): int
@@ -32,25 +39,161 @@ class PlatformDetectCli extends CliFramework
         $path = $this->getArgument('--path');
         $root = realpath($path) ?: $path;
 
-        // Check .mokogitea/manifest.xml first, fallback to root
-        $file = "{$root}/.mokogitea/manifest.xml";
-        if (!file_exists($file)) {
-            $file = "{$root}/.mokostandards";
-        }
-        if (!file_exists($file)) {
-            echo "unknown\n";
-            return 0;
+        $token = $this->getArgument('--token');
+        $giteaUrl = rtrim($this->getArgument('--gitea-url'), '/');
+        $owner = $this->getArgument('--owner');
+        $repo = $this->getArgument('--repo');
+        $doUpdate = $this->isFlagSet('--update');
+        $githubOutput = $this->isFlagSet('--github-output');
+
+        $platform = $this->detectPlatform($root);
+
+        $this->log('INFO', "Detected platform: {$platform}");
+        echo $platform . "\n";
+
+        // Append to $GITHUB_OUTPUT if requested
+        if ($githubOutput) {
+            $outputFile = getenv('GITHUB_OUTPUT');
+
+            if ($outputFile !== false && $outputFile !== '') {
+                file_put_contents($outputFile, "platform={$platform}\n", FILE_APPEND);
+                $this->log('INFO', "Appended platform={$platform} to \$GITHUB_OUTPUT");
+            } else {
+                $this->log('WARN', '$GITHUB_OUTPUT is not set; skipping output append.');
+            }
         }
 
-        $content = file_get_contents($file);
-        if (preg_match('/^platform:\s*(.+)/m', $content, $m)) {
-            echo trim($m[1], " \t\n\r\"'") . "\n";
-        } else {
-            echo "unknown\n";
+        // Update manifest via API if requested
+        if ($doUpdate) {
+            if ($token === '' || $owner === '' || $repo === '') {
+                $this->log('ERROR', '--update requires --token, --owner, and --repo.');
+                return 1;
+            }
+
+            if ($this->dryRun) {
+                $this->log('INFO', "[DRY RUN] Would update manifest.platform to \"{$platform}\" "
+                    . "for {$owner}/{$repo}.");
+                return 0;
+            }
+
+            $this->log('INFO', "Updating manifest.platform for {$owner}/{$repo} to \"{$platform}\"...");
+
+            $response = $this->apiRequest(
+                $giteaUrl,
+                $token,
+                'PATCH',
+                "/api/v1/repos/{$owner}/{$repo}/manifest",
+                json_encode(['platform' => $platform])
+            );
+
+            if ($response['code'] >= 200 && $response['code'] < 300) {
+                $this->log('INFO', "Manifest updated successfully (HTTP {$response['code']}).");
+            } else {
+                $this->log('ERROR', "Failed to update manifest (HTTP {$response['code']}): "
+                    . $response['body']);
+                return 1;
+            }
         }
 
         return 0;
     }
+
+    private function detectPlatform(string $root): string
+    {
+        // 1. Joomla — has pkg_*.xml or Joomla-style extension manifest
+        $joomlaIndicators = array_merge(
+            glob("{$root}/source/pkg_*.xml") ?: [],
+            glob("{$root}/pkg_*.xml") ?: [],
+            glob("{$root}/source/packages/*/services/provider.php") ?: [],
+            glob("{$root}/**/templateDetails.xml") ?: [],
+        );
+        if (!empty($joomlaIndicators)) {
+            return 'joomla';
+        }
+
+        // 2. Dolibarr — has mod*.class.php or dolibarr module descriptor
+        $doliIndicators = array_merge(
+            glob("{$root}/core/modules/mod*.class.php") ?: [],
+            glob("{$root}/class/*.class.php") ?: [],
+        );
+        if (!empty($doliIndicators) && file_exists("{$root}/langs")) {
+            return 'dolibarr';
+        }
+
+        // 3. Go — has go.mod
+        if (file_exists("{$root}/go.mod")) {
+            return 'go';
+        }
+
+        // 4. MCP — has package.json with mcp-related content or dist/index.js pattern
+        if (file_exists("{$root}/package.json")) {
+            $pkg = json_decode(file_get_contents("{$root}/package.json"), true);
+            $name = $pkg['name'] ?? '';
+            if (str_contains($name, 'mcp') || isset($pkg['dependencies']['@modelcontextprotocol/sdk'])) {
+                return 'mcp';
+            }
+        }
+
+        // 5. Platform — is mokoplatform itself or org-config
+        $repoName = basename($root);
+        if (in_array($repoName, ['mokoplatform', 'mokogitea-org-config'])) {
+            return 'platform';
+        }
+
+        // 6. Default
+        return 'generic';
+    }
+
+    private function isFlagSet(string $flag): bool
+    {
+        $value = $this->getArgument($flag);
+
+        return $value === 'true' || $value === '1' || $value === 'yes';
+    }
+
+    private function apiRequest(
+        string $giteaUrl,
+        string $token,
+        string $method,
+        string $endpoint,
+        ?string $body = null
+    ): array {
+        $url = $giteaUrl . $endpoint;
+
+        $ch = curl_init();
+        curl_setopt($ch, CURLOPT_URL, $url);
+        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
+        curl_setopt($ch, CURLOPT_HTTPHEADER, [
+            'Content-Type: application/json',
+            'Accept: application/json',
+            "Authorization: token {$token}",
+        ]);
+
+        if ($body !== null) {
+            curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+        }
+
+        $responseBody = curl_exec($ch);
+        $httpCode = (int) curl_getinfo(
+            $ch,
+            CURLINFO_HTTP_CODE
+        );
+
+        if (curl_errno($ch)) {
+            $error = curl_error($ch);
+            curl_close($ch);
+
+            return [
+                'code' => 0,
+                'body' => "cURL error: {$error}",
+            ];
+        }
+
+        curl_close($ch);
+
+        return ['code' => $httpCode, 'body' => $responseBody];
+    }
 }
 
 $app = new PlatformDetectCli();

cli/release_cascade.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/release_cascade.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: DEPRECATED — cascade behavior removed. Each release stream is independent.
  */
 

cli/release_create.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class ReleaseCreateCli extends CliFramework
 {
@@ -97,8 +97,8 @@ class ReleaseCreateCli extends CliFramework
         // Find extension manifest (Joomla XML)
         $extManifest = null;
         $manifestFiles = array_merge(
-            glob("{$root}/src/pkg_*.xml") ?: [],
-            glob("{$root}/src/*.xml") ?: [],
+            SourceResolver::globSource($root, 'pkg_*.xml'),
+            SourceResolver::globSource($root, '*.xml'),
             glob("{$root}/*.xml") ?: []
         );
         foreach ($manifestFiles as $file) {
@@ -112,8 +112,7 @@ class ReleaseCreateCli extends CliFramework
         // Find Dolibarr module file
         $modFile = null;
         $modFiles = array_merge(
-            glob("{$root}/src/core/modules/mod*.class.php") ?: [],
-            glob("{$root}/htdocs/core/modules/mod*.class.php") ?: [],
+            SourceResolver::globSource($root, 'core/modules/mod*.class.php'),
             glob("{$root}/core/modules/mod*.class.php") ?: []
         );
         foreach ($modFiles as $file) {

cli/release_package.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class ReleasePackageCli extends CliFramework
 {
@@ -99,9 +99,10 @@ class ReleasePackageCli extends CliFramework
         $extFolder = '';
         $typePrefix = '';
 
+        SourceResolver::warnIfLegacy($root);
         $manifestFiles = array_merge(
-            glob("{$root}/src/pkg_*.xml") ?: [],
-            glob("{$root}/src/*.xml") ?: [],
+            SourceResolver::globSource($root, 'pkg_*.xml'),
+            SourceResolver::globSource($root, '*.xml'),
             glob("{$root}/*.xml") ?: []
         );
 
@@ -200,14 +201,12 @@ class ReleasePackageCli extends CliFramework
             }
         }
 
-        if ($sourceDir === null && is_dir("{$root}/src")) {
-            $sourceDir = "{$root}/src";
-        } elseif ($sourceDir === null && is_dir("{$root}/htdocs")) {
-            $sourceDir = "{$root}/htdocs";
+        if ($sourceDir === null) {
+            $sourceDir = SourceResolver::resolveAbsolute($root);
         }
 
         if ($sourceDir === null) {
-            echo "No src/ or htdocs/ directory found — skipping package build\n";
+            echo "No source/ or src/ directory found — skipping package build\n";
             return 0;
         }
 
@@ -231,19 +230,20 @@ class ReleasePackageCli extends CliFramework
                 $subZipPath = "{$outputDir}/{$subName}.zip";
 
                 // If sub-package is a full repo checkout (e.g. git submodule),
-                // look for a src/ subdirectory containing a Joomla manifest XML
+                // look for a source/ or src/ subdirectory containing a Joomla manifest XML
                 // and zip that instead of the repo root.
                 $subSourceDir = $pkgDir;
-                $srcCandidate = "{$pkgDir}/src";
-                if (is_dir($srcCandidate)) {
+                $subSrcAbs = SourceResolver::resolveAbsolute($pkgDir);
+                if ($subSrcAbs !== null) {
                     $srcManifests = array_merge(
-                        glob("{$srcCandidate}/*.xml") ?: [],
-                        glob("{$srcCandidate}/pkg_*.xml") ?: []
+                        glob("{$subSrcAbs}/*.xml") ?: [],
+                        glob("{$subSrcAbs}/pkg_*.xml") ?: []
                     );
                     foreach ($srcManifests as $mf) {
                         if (strpos(file_get_contents($mf) ?: '', '<extension') !== false) {
-                            $subSourceDir = $srcCandidate;
-                            echo "  Sub-package {$subName}: using src/ entry-point\n";
+                            $subSourceDir = $subSrcAbs;
+                            $subSrcName = SourceResolver::resolve($pkgDir);
+                            echo "  Sub-package {$subName}: using {$subSrcName}/ entry-point\n";
                             break;
                         }
                     }

cli/release_promote.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class ReleasePromoteCli extends CliFramework
 {
@@ -109,8 +109,8 @@ class ReleasePromoteCli extends CliFramework
         if ($to === 'stable') {
             $root = realpath($path) ?: $path;
             $manifestFiles = array_merge(
-                glob("{$root}/src/pkg_*.xml") ?: [],
-                glob("{$root}/src/*.xml") ?: [],
+                SourceResolver::globSource($root, 'pkg_*.xml'),
+                SourceResolver::globSource($root, '*.xml'),
                 glob("{$root}/*.xml") ?: []
             );
             foreach ($manifestFiles as $xmlFile) {

cli/release_publish.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/release_publish.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Publish a release and create copies for all lesser stability streams.
  */
 

cli/release_validate.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class ReleaseValidateCli extends CliFramework
 {
@@ -66,8 +66,10 @@ class ReleaseValidateCli extends CliFramework
                 $platform = 'generic';
             }
         }
-        $hasSource = is_dir("{$root}/src") || is_dir("{$root}/htdocs");
-        $this->addVResult('Source directory', $hasSource ? 'PASS' : 'WARN', $hasSource ? 'src/ or htdocs/ found' : 'No src/ or htdocs/ directory');
+        $hasSource = SourceResolver::resolveAbsolute($root) !== null;
+        SourceResolver::warnIfLegacy($root);
+        $srcDirName = SourceResolver::resolve($root);
+        $this->addVResult('Source directory', $hasSource ? 'PASS' : 'WARN', $hasSource ? "{$srcDirName}/ found" : 'No source/ or src/ directory');
         if (!file_exists("{$root}/README.md")) {
             $this->addVResult('README.md', 'FAIL', 'Not found');
         } else {
@@ -109,7 +111,8 @@ class ReleaseValidateCli extends CliFramework
         $this->addVResult('LICENSE', $licenseFound ? 'PASS' : 'FAIL', $licenseFound ? 'Found' : 'Not found');
         if ($platform === 'joomla') {
             $manifest = null;
-            foreach (["{$root}/src", $root] as $dir) {
+            $srcAbs = SourceResolver::resolveAbsolute($root);
+            foreach (array_filter([$srcAbs, $root]) as $dir) {
                 if (!is_dir($dir)) {
                     continue;
                 } foreach (glob("{$dir}/*.xml") as $xmlFile) {
@@ -156,7 +159,7 @@ class ReleaseValidateCli extends CliFramework
             }
         } elseif ($platform === 'dolibarr') {
             $modFile = null;
-            foreach (['src', 'htdocs'] as $sd) {
+            foreach (SourceResolver::getCandidates() as $sd) {
                 $matches = glob("{$root}/{$sd}/mod*.class.php");
                 if (!empty($matches)) {
                     $modFile = $matches[0];

cli/scaffold_client.php

@@ -12,7 +12,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/scaffold_client.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Scaffold a new client-waas repo from Template-Client-WaaS with pre-configured settings
  */
 

cli/theme_lint.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class ThemeLintCli extends CliFramework
 {
@@ -41,17 +41,12 @@ class ThemeLintCli extends CliFramework
         $errors = 0;
         $warnings = 0;
 
-        $srcDir = null;
-        foreach (['src', 'htdocs'] as $d) {
-            if (is_dir("{$root}/{$d}")) {
-                $srcDir = "{$root}/{$d}";
-                break;
-            }
-        }
+        $srcDir = SourceResolver::resolveAbsolute($root);
         if ($srcDir === null) {
-            $this->log('ERROR', "No src/ or htdocs/ directory in {$root}");
+            $this->log('ERROR', "No source/ or src/ directory in {$root}");
             return 1;
         }
+        SourceResolver::warnIfLegacy($root);
 
         echo "Theme Lint: {$srcDir}\n\n";
 

cli/updates_xml_build.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class UpdatesXmlBuildCli extends CliFramework
 {
@@ -109,7 +109,7 @@ class UpdatesXmlBuildCli extends CliFramework
         // -- Locate Joomla manifest ---------------------------------------------------
         $manifest = null;
 
-        $candidates = glob("{$root}/src/pkg_*.xml") ?: [];
+        $candidates = SourceResolver::globSource($root, 'pkg_*.xml');
         foreach ($candidates as $f) {
             if (strpos(file_get_contents($f), '<extension') !== false) {
                 $manifest = $f;

cli/updates_xml_sync.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/updates_xml_sync.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Sync updates.xml to target branches via Gitea API
  * NOTE: Called by pre-release and auto-release workflows after updates.xml
  *       is modified on the current branch. Pushes the file to other branches

cli/version_auto_bump.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/version_auto_bump.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Auto patch-bump, set stability suffix, and commit — single CLI replacing inline workflow bash
  */
 

cli/version_bump.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class VersionBumpCli extends CliFramework
 {
@@ -42,6 +42,7 @@ class VersionBumpCli extends CliFramework
         $root = realpath($path) ?: $path;
         $mokoVersion = null;
         $existingSuffix = '';
+        $versionPrefix = '';
         $mokoManifest = "{$root}/.mokogitea/manifest.xml";
         $mokoContent = '';
         if (file_exists($mokoManifest)) {
@@ -50,29 +51,58 @@ class VersionBumpCli extends CliFramework
                 $mokoVersion = $m[1];
                 $existingSuffix = $m[2] ?? '';
             }
+            // Read version_prefix from manifest.xml (supports nested and flat structure)
+            $xml = @simplexml_load_file($mokoManifest);
+            if ($xml !== false) {
+                $prefix = (string)($xml->identity->version_prefix ?? '');
+                if ($prefix === '') {
+                    $prefix = (string)($xml->version_prefix ?? '');
+                }
+                $versionPrefix = $prefix;
+            }
         }
         $readmeVersion = null;
         $readme = "{$root}/README.md";
         $readmeContent = '';
         if (file_exists($readme)) {
             $readmeContent = file_get_contents($readme);
-            if (preg_match('/VERSION:\s*(\d{2}\.\d{2}\.\d{2})/m', $readmeContent, $m)) {
+            if (!empty($versionPrefix)) {
+                // Prefix-aware README scan
+                $prefixPattern = preg_quote($versionPrefix, '/');
+                if (preg_match('/' . $prefixPattern . '(\d{2}\.\d{2}\.\d{2})/m', $readmeContent, $m)) {
+                    $readmeVersion = $m[1];
+                }
+            }
+            if ($readmeVersion === null && preg_match('/VERSION:\s*(\d{2}\.\d{2}\.\d{2})/m', $readmeContent, $m)) {
                 $readmeVersion = $m[1];
             }
         }
         $manifestVersion = null;
+        SourceResolver::warnIfLegacy($root);
         $manifestFiles = array_merge(
-            glob("{$root}/src/pkg_*.xml") ?: [],
-            glob("{$root}/src/*.xml") ?: [],
-            glob("{$root}/src/packages/*/mokowaas.xml") ?: [],
-            glob("{$root}/src/packages/*/*.xml") ?: [],
+            SourceResolver::globSource($root, 'pkg_*.xml'),
+            SourceResolver::globSource($root, '*.xml'),
+            SourceResolver::globSource($root, 'packages/*/mokowaas.xml'),
+            SourceResolver::globSource($root, 'packages/*/*.xml'),
             glob("{$root}/*.xml") ?: []
         );
         foreach ($manifestFiles as $xmlFile) {
             $xmlContent = file_get_contents($xmlFile);
             if (strpos($xmlContent, '<extension') === false && strpos($xmlContent, '<version>') === false) {
                 continue;
-            } if (preg_match('#<version>(\d{2}\.\d{2}\.\d{2})((?:-(?:dev|alpha|beta|rc))+)?</version>#', $xmlContent, $xm)) {
+            }
+            if (!empty($versionPrefix)) {
+                // Prefix-aware: look for <version>prefix + XX.YY.ZZ</version>
+                $prefixPattern = preg_quote($versionPrefix, '#');
+                if (preg_match('#<version>' . $prefixPattern . '(\d{2}\.\d{2}\.\d{2})</version>#', $xmlContent, $xm)) {
+                    $candidate = $xm[1];
+                    if ($manifestVersion === null || version_compare($candidate, $manifestVersion, '>')) {
+                        $manifestVersion = $candidate;
+                    }
+                    continue;
+                }
+            }
+            if (preg_match('#<version>(\d{2}\.\d{2}\.\d{2})((?:-(?:dev|alpha|beta|rc))+)?</version>#', $xmlContent, $xm)) {
                 $candidate = $xm[1];
                 if ($manifestVersion === null || version_compare($candidate, $manifestVersion, '>')) {
                     $manifestVersion = $candidate;
@@ -135,25 +165,43 @@ class VersionBumpCli extends CliFramework
             }
         }
         if (file_exists($readme) && !empty($readmeContent)) {
-            $updated = preg_replace('/(VERSION:\s*)\d{2}\.\d{2}\.\d{2}(?:(?:-(?:dev|alpha|beta|rc))+)?/m', '${1}' . $newBase, $readmeContent, 1);
+            if (!empty($versionPrefix)) {
+                // Prefix-aware README replacement: preserve prefix, replace only version part
+                $prefixPattern = preg_quote($versionPrefix, '/');
+                $updated = preg_replace('/(' . $prefixPattern . ')\d{2}\.\d{2}\.\d{2}/m', '${1}' . $newBase, $readmeContent, 1);
+            } else {
+                $updated = preg_replace('/(VERSION:\s*)\d{2}\.\d{2}\.\d{2}(?:(?:-(?:dev|alpha|beta|rc))+)?/m', '${1}' . $newBase, $readmeContent, 1);
+            }
             if ($updated !== null) {
                 file_put_contents($readme, $updated);
             }
         }
         $updatedFiles = [];
-        foreach (["{$root}/src/pkg_*.xml", "{$root}/src/*.xml", "{$root}/src/packages/*/*.xml", "{$root}/*.xml"] as $pattern) {
+        $srcName = SourceResolver::resolve($root);
+        foreach (["{$root}/{$srcName}/pkg_*.xml", "{$root}/{$srcName}/*.xml", "{$root}/{$srcName}/packages/*/*.xml", "{$root}/*.xml"] as $pattern) {
             foreach (glob($pattern) ?: [] as $xmlFile) {
                 $content = file_get_contents($xmlFile);
                 if (strpos($content, '<extension') === false) {
                     continue;
                 }
-                $xmlPattern = '#<version>\d{2}\.\d{2}\.\d{2}'
-                    . '(?:(?:-(?:dev|alpha|beta|rc))+)?</version>#';
-                $newContent = preg_replace(
-                    $xmlPattern,
-                    "<version>{$newFull}</version>",
-                    $content
-                );
+                if (!empty($versionPrefix)) {
+                    // Prefix-aware: preserve prefix, replace only the Moko version part
+                    $prefixPattern = preg_quote($versionPrefix, '#');
+                    $xmlPattern = '#(<version>' . $prefixPattern . ')\d{2}\.\d{2}\.\d{2}</version>#';
+                    $newContent = preg_replace(
+                        $xmlPattern,
+                        '${1}' . $newBase . '</version>',
+                        $content
+                    );
+                } else {
+                    $xmlPattern = '#<version>\d{2}\.\d{2}\.\d{2}'
+                        . '(?:(?:-(?:dev|alpha|beta|rc))+)?</version>#';
+                    $newContent = preg_replace(
+                        $xmlPattern,
+                        "<version>{$newFull}</version>",
+                        $content
+                    );
+                }
                 if ($newContent !== null && $newContent !== $content) {
                     file_put_contents($xmlFile, $newContent);
                     $updatedFiles[] = substr($xmlFile, strlen($root) + 1);
@@ -166,13 +214,24 @@ class VersionBumpCli extends CliFramework
         $packageJsonFile = "{$root}/package.json";
         if (file_exists($packageJsonFile)) {
             $pkgContent = file_get_contents($packageJsonFile);
-            $pkgPattern = '/("version"\s*:\s*")\d{2}\.\d{2}\.\d{2}'
-                . '(?:(?:-(?:dev|alpha|beta|rc))+)?(")/m';
-            $updatedPkg = preg_replace(
-                $pkgPattern,
-                '${1}' . $newFull . '${2}',
-                $pkgContent
-            );
+            if (!empty($versionPrefix)) {
+                // Prefix-aware package.json replacement
+                $prefixPattern = preg_quote($versionPrefix, '/');
+                $pkgPattern = '/("version"\s*:\s*")' . $prefixPattern . '\d{2}\.\d{2}\.\d{2}(")/m';
+                $updatedPkg = preg_replace(
+                    $pkgPattern,
+                    '${1}' . $versionPrefix . $newBase . '${2}',
+                    $pkgContent
+                );
+            } else {
+                $pkgPattern = '/("version"\s*:\s*")\d{2}\.\d{2}\.\d{2}'
+                    . '(?:(?:-(?:dev|alpha|beta|rc))+)?(")/m';
+                $updatedPkg = preg_replace(
+                    $pkgPattern,
+                    '${1}' . $newFull . '${2}',
+                    $pkgContent
+                );
+            }
             if ($updatedPkg !== $pkgContent) {
                 file_put_contents($packageJsonFile, $updatedPkg);
                 fwrite(STDERR, "Updated package.json\n");
@@ -181,13 +240,24 @@ class VersionBumpCli extends CliFramework
         $pyprojectFile = "{$root}/pyproject.toml";
         if (file_exists($pyprojectFile)) {
             $pyContent = file_get_contents($pyprojectFile);
-            $pyPattern = '/^(version\s*=\s*")\d{2}\.\d{2}\.\d{2}'
-                . '(?:(?:-(?:dev|alpha|beta|rc))+)?(")/m';
-            $updatedPy = preg_replace(
-                $pyPattern,
-                '${1}' . $newFull . '${2}',
-                $pyContent
-            );
+            if (!empty($versionPrefix)) {
+                // Prefix-aware pyproject.toml replacement
+                $prefixPattern = preg_quote($versionPrefix, '/');
+                $pyPattern = '/^(version\s*=\s*")' . $prefixPattern . '\d{2}\.\d{2}\.\d{2}(")/m';
+                $updatedPy = preg_replace(
+                    $pyPattern,
+                    '${1}' . $versionPrefix . $newBase . '${2}',
+                    $pyContent
+                );
+            } else {
+                $pyPattern = '/^(version\s*=\s*")\d{2}\.\d{2}\.\d{2}'
+                    . '(?:(?:-(?:dev|alpha|beta|rc))+)?(")/m';
+                $updatedPy = preg_replace(
+                    $pyPattern,
+                    '${1}' . $newFull . '${2}',
+                    $pyContent
+                );
+            }
             if ($updatedPy !== $pyContent) {
                 file_put_contents($pyprojectFile, $updatedPy);
                 fwrite(STDERR, "Updated pyproject.toml\n");
@@ -204,7 +274,13 @@ class VersionBumpCli extends CliFramework
         }
         $scanExtensions = ['php', 'yml', 'yaml', 'md', 'txt', 'xml', 'sh', 'toml', 'ini', 'css', 'js'];
         $excludeDirs = ['.git', 'vendor', 'node_modules', 'build', 'dist', '.claude'];
-        $versionPattern = '/(VERSION:\s*)\d{2}\.\d{2}\.\d{2}/m';
+        // Build the generic VERSION: pattern — prefix-aware if configured
+        if (!empty($versionPrefix)) {
+            $prefixPatternGeneric = preg_quote($versionPrefix, '/');
+            $versionPattern = '/(' . $prefixPatternGeneric . ')\d{2}\.\d{2}\.\d{2}/m';
+        } else {
+            $versionPattern = '/(VERSION:\s*)\d{2}\.\d{2}\.\d{2}/m';
+        }
         $directory = new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS);
         $filter = new RecursiveCallbackFilterIterator($directory, function ($current, $key, $iterator) use ($excludeDirs) {
             if ($current->isDir() && in_array($current->getFilename(), $excludeDirs, true)) {

cli/version_bump_remote.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class VersionBumpRemoteCli extends CliFramework
 {
@@ -104,11 +104,15 @@ class VersionBumpRemoteCli extends CliFramework
         $nextVersion = sprintf('%02d.%02d.%02d', $major, $minor, $patch);
         echo "{$version} -> {$nextVersion} ({$branch})\n";
 
+        // Try both source/ and src/ paths for backwards compatibility with remote repos
         $manifestPaths = [];
-        if ($manifestFile !== null) {
-            $manifestPaths[] = "src/{$manifestFile}";
+        foreach (['source', 'src'] as $srcPrefix) {
+            if ($manifestFile !== null) {
+                $manifestPaths[] = "{$srcPrefix}/{$manifestFile}";
+            }
+            $manifestPaths[] = "{$srcPrefix}/templateDetails.xml";
+            $manifestPaths[] = "{$srcPrefix}/manifest.xml";
         }
-        $manifestPaths = array_merge($manifestPaths, ['src/templateDetails.xml', 'src/manifest.xml']);
         $manifestUpdated = false;
         foreach ($manifestPaths as $mPath) {
             $result = $this->updateRemoteFile($apiBase, $token, $mPath, $branch, function (string $content) use ($version, $nextVersion): string {

cli/version_check.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/version_check.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Validate version consistency across README, manifests, and sub-packages
  */
 
@@ -18,7 +18,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class VersionCheckCli extends CliFramework
 {
@@ -77,7 +77,8 @@ class VersionCheckCli extends CliFramework
                 $versions['pyproject.toml'] = $m[1];
             }
         }
-        foreach (["{$root}/src/pkg_*.xml", "{$root}/src/*.xml", "{$root}/src/packages/*/*.xml", "{$root}/*.xml"] as $glob) {
+        $srcName = SourceResolver::resolve($root);
+        foreach (["{$root}/{$srcName}/pkg_*.xml", "{$root}/{$srcName}/*.xml", "{$root}/{$srcName}/packages/*/*.xml", "{$root}/*.xml"] as $glob) {
             foreach (glob($glob) ?: [] as $file) {
                 if (basename($file) === 'updates.xml') {
                     continue;

cli/version_read.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class VersionReadCli extends CliFramework
 {
@@ -34,6 +34,7 @@ class VersionReadCli extends CliFramework
 
         // -- 1. Read from .mokogitea/manifest.xml (canonical source) --
         $mokoVersion = null;
+        $versionPrefix = '';
         $mokoManifest = "{$root}/.mokogitea/manifest.xml";
         if (file_exists($mokoManifest)) {
             $xml = @simplexml_load_file($mokoManifest);
@@ -42,6 +43,12 @@ class VersionReadCli extends CliFramework
                 if (preg_match('/^\d{2}\.\d{2}\.\d{2}((?:-(?:dev|alpha|beta|rc))+)?$/', $v)) {
                     $mokoVersion = $v;
                 }
+                // Read version_prefix (supports both nested and flat structure)
+                $prefix = (string)($xml->identity->version_prefix ?? '');
+                if ($prefix === '') {
+                    $prefix = (string)($xml->version_prefix ?? '');
+                }
+                $versionPrefix = $prefix;
             }
         }
 
@@ -56,7 +63,14 @@ class VersionReadCli extends CliFramework
         $readme = "{$root}/README.md";
         if (file_exists($readme)) {
             $content = file_get_contents($readme);
-            if (preg_match('/VERSION:\s*(\d{2}\.\d{2}\.\d{2})/m', $content, $m)) {
+            if (!empty($versionPrefix)) {
+                // Prefix-aware: search for prefix followed by version
+                $prefixPattern = preg_quote($versionPrefix, '/');
+                if (preg_match('/' . $prefixPattern . '(\d{2}\.\d{2}\.\d{2})/m', $content, $m)) {
+                    $readmeVersion = $m[1];
+                }
+            }
+            if ($readmeVersion === null && preg_match('/VERSION:\s*(\d{2}\.\d{2}\.\d{2})/m', $content, $m)) {
                 $readmeVersion = $m[1];
             }
         }
@@ -64,9 +78,9 @@ class VersionReadCli extends CliFramework
         // -- 3. Fallback: Joomla manifest XML --
         $manifestVersion = null;
         $manifestFiles = array_merge(
-            glob("{$root}/src/pkg_*.xml") ?: [],
-            glob("{$root}/src/*.xml") ?: [],
-            glob("{$root}/src/packages/*/*.xml") ?: [],
+            SourceResolver::globSource($root, 'pkg_*.xml'),
+            SourceResolver::globSource($root, '*.xml'),
+            SourceResolver::globSource($root, 'packages/*/*.xml'),
             glob("{$root}/*.xml") ?: []
         );
 
@@ -75,10 +89,22 @@ class VersionReadCli extends CliFramework
             if (strpos($xmlContent, '<extension') === false && strpos($xmlContent, '<version>') === false) {
                 continue;
             }
+            if (!empty($versionPrefix)) {
+                // Prefix-aware: look for <version>prefix + XX.YY.ZZ</version>
+                $prefixPattern = preg_quote($versionPrefix, '#');
+                if (preg_match('#<version>' . $prefixPattern . '(\d{2}\.\d{2}\.\d{2})</version>#', $xmlContent, $xm)) {
+                    $candidate = $xm[1];
+                    $currentBase = $manifestVersion ? preg_replace('/(-(?:dev|alpha|beta|rc))+$/', '', $manifestVersion) : null;
+                    if ($currentBase === null || version_compare($candidate, $currentBase, '>')) {
+                        $manifestVersion = $candidate;
+                    }
+                    continue;
+                }
+            }
             if (preg_match('#<version>(\d{2}\.\d{2}\.\d{2}(?:(?:-(?:dev|alpha|beta|rc))+)?)</version>#', $xmlContent, $xm)) {
                 $candidate = $xm[1];
-                $candidateBase = preg_replace('/(-(dev|alpha|beta|rc))+$/', '', $candidate);
-                $currentBase = $manifestVersion ? preg_replace('/(-(dev|alpha|beta|rc))+$/', '', $manifestVersion) : null;
+                $candidateBase = preg_replace('/(-(?:dev|alpha|beta|rc))+$/', '', $candidate);
+                $currentBase = $manifestVersion ? preg_replace('/(-(?:dev|alpha|beta|rc))+$/', '', $manifestVersion) : null;
                 if ($currentBase === null || version_compare($candidateBase, $currentBase, '>')) {
                     $manifestVersion = $candidate;
                 }

cli/version_set_platform.php

@@ -17,7 +17,7 @@ declare(strict_types=1);
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 
 class VersionSetPlatformCli extends CliFramework
 {
@@ -110,7 +110,8 @@ class VersionSetPlatformCli extends CliFramework
 
         // Dolibarr: $this->version + $this->url_last_version in mod*.class.php
         if ($platform === 'crm-module') {
-            $pattern = "{$root}/src/core/modules/mod*.class.php";
+            $srcName = SourceResolver::resolve($root);
+            $pattern = "{$root}/{$srcName}/core/modules/mod*.class.php";
             foreach (glob($pattern) ?: [] as $file) {
                 $content = file_get_contents($file);
 
@@ -146,9 +147,10 @@ class VersionSetPlatformCli extends CliFramework
 
         // Joomla: <version> in XML manifests (top-level + sub-packages)
         if (in_array($platform, ['waas-component', 'joomla'], true)) {
+            $srcName = SourceResolver::resolve($root);
             $xmlFiles = array_merge(
-                glob("{$root}/src/*.xml") ?: [],
-                glob("{$root}/src/packages/*/*.xml") ?: [],
+                glob("{$root}/{$srcName}/*.xml") ?: [],
+                glob("{$root}/{$srcName}/packages/*/*.xml") ?: [],
                 glob("{$root}/*.xml") ?: []
             );
             if (empty($xmlFiles)) {

cli/wiki_sync.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/wiki_sync.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Sync select wiki pages from moko-platform to all template repos
  */
 

cli/workflow_sync.php

@@ -0,0 +1,646 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: moko-platform.CLI
+ * INGROUP: moko-platform
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /cli/workflow_sync.php
+ * VERSION: 09.25.02
+ * BRIEF: Sync workflows from Generic → platform templates → live repos based on manifest.platform
+ */
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
+
+use MokoEnterprise\CliFramework;
+
+class WorkflowSyncCli extends CliFramework
+{
+    private const PLATFORM_TEMPLATES = [
+        'joomla'   => 'Template-Joomla',
+        'dolibarr' => 'Template-Dolibarr',
+        'go'       => 'Template-Go',
+        'mcp'      => 'Template-MCP',
+        'platform' => 'Template-Generic',
+        'generic'  => 'Template-Generic',
+    ];
+
+    private const DEFAULT_TEMPLATE = 'Template-Generic';
+    private const GENERIC_TEMPLATE = 'Template-Generic';
+
+    private int $updated = 0;
+    private int $created = 0;
+    private int $skipped = 0;
+    private int $errors = 0;
+
+    protected function configure(): void
+    {
+        $this->setDescription('Sync workflows from Generic → platform templates → live repos based on manifest.platform');
+        $this->addArgument('--gitea-url', 'Gitea URL (default: https://git.mokoconsulting.tech)', 'https://git.mokoconsulting.tech');
+        $this->addArgument('--token', 'Gitea API token', '');
+        $this->addArgument('--org', 'Target organization', '');
+        $this->addArgument('--branch', 'Target branch (default: main)', 'main');
+        $this->addArgument('--phase', 'Phase to run: all, templates, repos (default: all)', 'all');
+        $this->addArgument('--platform-filter', 'Only sync repos matching this platform', '');
+    }
+
+    protected function run(): int
+    {
+        $giteaUrl = rtrim($this->getArgument('--gitea-url'), '/');
+        $token = $this->getArgument('--token');
+        $org = $this->getArgument('--org');
+        $branch = $this->getArgument('--branch');
+        $phase = $this->getArgument('--phase');
+        $platformFilter = $this->getArgument('--platform-filter');
+
+        if ($token === '') {
+            $this->log('ERROR', '--token is required.');
+            return 1;
+        }
+
+        if ($org === '') {
+            $this->log('ERROR', '--org is required.');
+            return 1;
+        }
+
+        if (!in_array($phase, ['all', 'templates', 'repos'], true)) {
+            $this->log('ERROR', "--phase must be one of: all, templates, repos (got: {$phase})");
+            return 1;
+        }
+
+        $this->log('INFO', "Workflow Sync — org: {$org}, branch: {$branch}, phase: {$phase}");
+
+        if ($platformFilter !== '') {
+            $this->log('INFO', "Platform filter: {$platformFilter}");
+        }
+
+        if ($this->dryRun) {
+            $this->log('INFO', '[DRY RUN] No changes will be made.');
+        }
+
+        echo "\n";
+
+        // Phase 1: Sync Generic → Platform Templates
+        if ($phase === 'all' || $phase === 'templates') {
+            $result = $this->syncGenericToTemplates($giteaUrl, $token, $org, $branch, $platformFilter);
+
+            if ($result !== 0) {
+                return $result;
+            }
+        }
+
+        // Phase 2: Sync Platform Templates → Live Repos
+        if ($phase === 'all' || $phase === 'repos') {
+            $result = $this->syncTemplatesToRepos($giteaUrl, $token, $org, $branch, $platformFilter);
+
+            if ($result !== 0) {
+                return $result;
+            }
+        }
+
+        echo "\n";
+        $this->log('INFO', "Done: {$this->created} created, {$this->updated} updated, "
+            . "{$this->skipped} skipped, {$this->errors} error(s).");
+
+        return $this->errors > 0 ? 1 : 0;
+    }
+
+    /**
+     * Phase 1: Push all Generic workflows to each platform template repo.
+     * Skips platform-specific overrides (files that exist in the platform template but NOT in Generic).
+     */
+    private function syncGenericToTemplates(
+        string $giteaUrl,
+        string $token,
+        string $org,
+        string $branch,
+        string $platformFilter
+    ): int {
+        $this->log('INFO', '=== Phase 1: Sync Generic → Platform Templates ===');
+        echo "\n";
+
+        // Get all workflow files from Template-Generic
+        $genericWorkflows = $this->listWorkflows($giteaUrl, $token, $org, self::GENERIC_TEMPLATE, $branch);
+
+        if ($genericWorkflows === null) {
+            $this->log('ERROR', 'Could not list workflows from ' . self::GENERIC_TEMPLATE);
+            return 1;
+        }
+
+        if (count($genericWorkflows) === 0) {
+            $this->log('WARN', 'No workflows found in ' . self::GENERIC_TEMPLATE);
+            return 0;
+        }
+
+        $this->log('INFO', 'Found ' . count($genericWorkflows) . ' workflow(s) in ' . self::GENERIC_TEMPLATE);
+        echo "\n";
+
+        // Get unique platform templates (exclude Generic itself)
+        $platformTemplates = array_unique(array_filter(
+            array_values(self::PLATFORM_TEMPLATES),
+            fn(string $t) => $t !== self::GENERIC_TEMPLATE
+        ));
+
+        // If platform-filter is set, only sync to the matching template
+        if ($platformFilter !== '') {
+            $targetTemplate = self::PLATFORM_TEMPLATES[$platformFilter] ?? null;
+
+            if ($targetTemplate === null || $targetTemplate === self::GENERIC_TEMPLATE) {
+                $this->log('INFO', "Platform filter '{$platformFilter}' does not map to a non-generic template, skipping Phase 1.");
+                return 0;
+            }
+
+            $platformTemplates = [$targetTemplate];
+        }
+
+        fprintf(STDERR, "%-45s | %s\n", 'Template / File', 'Status');
+        fprintf(STDERR, "%s\n", str_repeat('-', 70));
+
+        foreach ($platformTemplates as $templateRepo) {
+            foreach ($genericWorkflows as $workflow) {
+                $filename = $workflow['name'];
+                $destPath = '.mokogitea/workflows/' . $filename;
+                $label = "{$templateRepo}/{$filename}";
+
+                // Get file content from Generic
+                $sourceContent = $this->getFileContent(
+                    $giteaUrl, $token, $org,
+                    self::GENERIC_TEMPLATE, $destPath, $branch
+                );
+
+                if ($sourceContent === null) {
+                    fprintf(STDERR, "%-45s | %s\n", $label, 'ERROR (read source)');
+                    $this->errors++;
+                    continue;
+                }
+
+                $commitMsg = "chore: sync {$filename} from " . self::GENERIC_TEMPLATE . " [skip ci]";
+
+                $this->pushFile(
+                    $giteaUrl, $token, $org, $templateRepo,
+                    $destPath, $sourceContent, $branch, $commitMsg, $label
+                );
+            }
+        }
+
+        echo "\n";
+        return 0;
+    }
+
+    /**
+     * Phase 2: Sync platform template workflows to live repos based on manifest.platform.
+     */
+    private function syncTemplatesToRepos(
+        string $giteaUrl,
+        string $token,
+        string $org,
+        string $branch,
+        string $platformFilter
+    ): int {
+        $this->log('INFO', '=== Phase 2: Sync Platform Templates → Live Repos ===');
+        echo "\n";
+
+        $repos = $this->fetchOrgRepos($giteaUrl, $token, $org);
+
+        if ($repos === null) {
+            return 1;
+        }
+
+        $this->log('INFO', 'Found ' . count($repos) . " repo(s) in \"{$org}\".");
+        echo "\n";
+
+        fprintf(STDERR, "%-45s | %s\n", 'Repo / File', 'Status');
+        fprintf(STDERR, "%s\n", str_repeat('-', 70));
+
+        // Cache template workflows to avoid repeated API calls
+        $templateWorkflowCache = [];
+
+        foreach ($repos as $repoFullName) {
+            [, $repoName] = explode('/', $repoFullName, 2);
+
+            // Skip template repos
+            if (str_starts_with($repoName, 'Template-')) {
+                continue;
+            }
+
+            // Read manifest.platform
+            $platform = $this->getRepoPlatform($giteaUrl, $token, $org, $repoName, $branch);
+
+            // Apply platform filter
+            if ($platformFilter !== '' && $platform !== $platformFilter) {
+                continue;
+            }
+
+            // Resolve template
+            $templateRepo = self::PLATFORM_TEMPLATES[$platform] ?? self::DEFAULT_TEMPLATE;
+
+            // Get workflows from the template (cached)
+            if (!isset($templateWorkflowCache[$templateRepo])) {
+                $workflows = $this->listWorkflows($giteaUrl, $token, $org, $templateRepo, $branch);
+
+                if ($workflows === null) {
+                    $this->log('WARN', "Could not list workflows from {$templateRepo}, falling back to " . self::GENERIC_TEMPLATE);
+                    $workflows = $this->listWorkflows($giteaUrl, $token, $org, self::GENERIC_TEMPLATE, $branch);
+                }
+
+                $templateWorkflowCache[$templateRepo] = $workflows ?? [];
+            }
+
+            $workflows = $templateWorkflowCache[$templateRepo];
+
+            if (count($workflows) === 0) {
+                continue;
+            }
+
+            foreach ($workflows as $workflow) {
+                $filename = $workflow['name'];
+                $destPath = '.mokogitea/workflows/' . $filename;
+                $label = "{$repoFullName}/{$filename}";
+
+                // Get source content from template
+                $sourceContent = $this->getFileContent(
+                    $giteaUrl, $token, $org,
+                    $templateRepo, $destPath, $branch
+                );
+
+                if ($sourceContent === null) {
+                    fprintf(STDERR, "%-45s | %s\n", $label, 'ERROR (read source)');
+                    $this->errors++;
+                    continue;
+                }
+
+                $commitMsg = "chore: sync {$filename} from {$templateRepo} [skip ci]";
+
+                $this->pushFile(
+                    $giteaUrl, $token, $org, $repoName,
+                    $destPath, $sourceContent, $branch, $commitMsg, $label
+                );
+            }
+        }
+
+        echo "\n";
+        return 0;
+    }
+
+    /**
+     * Push a file to a repo — create or update, skip if identical.
+     */
+    private function pushFile(
+        string $giteaUrl,
+        string $token,
+        string $org,
+        string $repoName,
+        string $destPath,
+        string $localContent,
+        string $branch,
+        string $commitMsg,
+        string $label
+    ): void {
+        $existing = $this->apiRequest(
+            $giteaUrl,
+            $token,
+            'GET',
+            "/api/v1/repos/{$org}/{$repoName}/contents/"
+                . "{$destPath}?ref={$branch}"
+        );
+
+        $encodedContent = base64_encode($localContent);
+
+        if ($existing['code'] === 200) {
+            $data = json_decode($existing['body'], true);
+            $remoteSha = $data['sha'] ?? '';
+            $remoteContent = base64_decode($data['content'] ?? '');
+
+            if ($remoteContent === $localContent) {
+                fprintf(STDERR, "%-45s | %s\n", $label, 'IDENTICAL (skipped)');
+                $this->skipped++;
+                return;
+            }
+
+            if ($this->dryRun) {
+                fprintf(STDERR, "%-45s | %s\n", $label, 'WOULD UPDATE');
+                $this->updated++;
+                return;
+            }
+
+            $payload = json_encode([
+                'content' => $encodedContent,
+                'sha' => $remoteSha,
+                'message' => $commitMsg,
+                'branch' => $branch,
+            ]);
+
+            $response = $this->apiRequest(
+                $giteaUrl,
+                $token,
+                'PUT',
+                "/api/v1/repos/{$org}/{$repoName}/contents/" . $destPath,
+                $payload
+            );
+
+            if ($response['code'] === 200) {
+                fprintf(STDERR, "%-45s | %s\n", $label, 'UPDATED');
+                $this->updated++;
+            } else {
+                fprintf(STDERR, "%-45s | %s\n", $label, "ERROR (HTTP {$response['code']})");
+                $this->errors++;
+            }
+        } elseif ($existing['code'] === 404) {
+            if ($this->dryRun) {
+                fprintf(STDERR, "%-45s | %s\n", $label, 'WOULD CREATE');
+                $this->created++;
+                return;
+            }
+
+            $payload = json_encode([
+                'content' => $encodedContent,
+                'message' => $commitMsg,
+                'branch' => $branch,
+            ]);
+
+            $response = $this->apiRequest(
+                $giteaUrl,
+                $token,
+                'POST',
+                "/api/v1/repos/{$org}/{$repoName}/contents/" . $destPath,
+                $payload
+            );
+
+            if ($response['code'] === 201) {
+                fprintf(STDERR, "%-45s | %s\n", $label, 'CREATED');
+                $this->created++;
+            } else {
+                fprintf(STDERR, "%-45s | %s\n", $label, "ERROR (HTTP {$response['code']})");
+                $this->errors++;
+            }
+        } else {
+            fprintf(STDERR, "%-45s | %s\n", $label, "ERROR (HTTP {$existing['code']})");
+            $this->errors++;
+        }
+    }
+
+    /**
+     * List workflow files in a repo's .mokogitea/workflows/ directory.
+     */
+    private function listWorkflows(
+        string $giteaUrl,
+        string $token,
+        string $org,
+        string $repoName,
+        string $branch
+    ): ?array {
+        $response = $this->apiRequest(
+            $giteaUrl,
+            $token,
+            'GET',
+            "/api/v1/repos/{$org}/{$repoName}/contents/.mokogitea/workflows?ref={$branch}"
+        );
+
+        if ($response['code'] !== 200) {
+            return null;
+        }
+
+        $data = json_decode($response['body'], true);
+
+        if (!is_array($data)) {
+            return null;
+        }
+
+        // Filter to only files (not directories)
+        return array_values(array_filter($data, fn($item) => ($item['type'] ?? '') === 'file'));
+    }
+
+    /**
+     * Get file content from a repo as a raw string.
+     */
+    private function getFileContent(
+        string $giteaUrl,
+        string $token,
+        string $org,
+        string $repoName,
+        string $filePath,
+        string $branch
+    ): ?string {
+        $response = $this->apiRequest(
+            $giteaUrl,
+            $token,
+            'GET',
+            "/api/v1/repos/{$org}/{$repoName}/contents/{$filePath}?ref={$branch}"
+        );
+
+        if ($response['code'] !== 200) {
+            return null;
+        }
+
+        $data = json_decode($response['body'], true);
+
+        if (!is_array($data) || !isset($data['content'])) {
+            return null;
+        }
+
+        return base64_decode($data['content']);
+    }
+
+    /**
+     * Read a repo's manifest.xml and extract the platform value.
+     * Returns 'generic' if the manifest is missing or has no platform field.
+     */
+    private function getRepoPlatform(
+        string $giteaUrl,
+        string $token,
+        string $org,
+        string $repoName,
+        string $branch
+    ): string {
+        $response = $this->apiRequest(
+            $giteaUrl,
+            $token,
+            'GET',
+            "/api/v1/repos/{$org}/{$repoName}/contents/.mokogitea/manifest.xml?ref={$branch}"
+        );
+
+        if ($response['code'] !== 200) {
+            return 'generic';
+        }
+
+        $data = json_decode($response['body'], true);
+
+        if (!is_array($data) || !isset($data['content'])) {
+            return 'generic';
+        }
+
+        $xmlContent = base64_decode($data['content']);
+
+        if ($xmlContent === false || $xmlContent === '') {
+            return 'generic';
+        }
+
+        // Suppress XML warnings for malformed manifests
+        $previous = libxml_use_internal_errors(true);
+        $xml = simplexml_load_string($xmlContent);
+        libxml_use_internal_errors($previous);
+
+        if ($xml === false) {
+            return 'generic';
+        }
+
+        // Try <governance><platform> (standard location)
+        $platform = '';
+
+        // Register namespace if present
+        $namespaces = $xml->getNamespaces(true);
+
+        if (!empty($namespaces)) {
+            $ns = reset($namespaces);
+            $xml->registerXPathNamespace('mp', $ns);
+
+            $nodes = $xml->xpath('//mp:governance/mp:platform');
+
+            if (!empty($nodes)) {
+                $platform = trim((string) $nodes[0]);
+            }
+
+            // Fallback: <identity><platform>
+            if ($platform === '') {
+                $nodes = $xml->xpath('//mp:identity/mp:platform');
+
+                if (!empty($nodes)) {
+                    $platform = trim((string) $nodes[0]);
+                }
+            }
+
+            // Fallback: top-level <platform>
+            if ($platform === '') {
+                $nodes = $xml->xpath('//mp:platform');
+
+                if (!empty($nodes)) {
+                    $platform = trim((string) $nodes[0]);
+                }
+            }
+        } else {
+            // No namespace
+            if (isset($xml->governance->platform)) {
+                $platform = trim((string) $xml->governance->platform);
+            } elseif (isset($xml->identity->platform)) {
+                $platform = trim((string) $xml->identity->platform);
+            } elseif (isset($xml->platform)) {
+                $platform = trim((string) $xml->platform);
+            }
+        }
+
+        if ($platform === '') {
+            return 'generic';
+        }
+
+        return strtolower($platform);
+    }
+
+    /**
+     * Fetch all non-archived repos in an org (paginated).
+     */
+    private function fetchOrgRepos(string $giteaUrl, string $token, string $org): ?array
+    {
+        $this->log('INFO', "Fetching repos from org: {$org}");
+
+        $page = 1;
+        $repos = [];
+
+        while (true) {
+            $response = $this->apiRequest(
+                $giteaUrl,
+                $token,
+                'GET',
+                "/api/v1/orgs/{$org}/repos?"
+                    . "limit=50&page={$page}"
+            );
+
+            if ($response['code'] < 200 || $response['code'] >= 300) {
+                if ($page === 1) {
+                    $this->log('ERROR', "Could not fetch repos "
+                        . "(HTTP {$response['code']}).");
+                    return null;
+                }
+
+                break;
+            }
+
+            $data = json_decode($response['body'], true);
+
+            if (!is_array($data) || count($data) === 0) {
+                break;
+            }
+
+            foreach ($data as $repo) {
+                if (!empty($repo['archived'])) {
+                    continue;
+                }
+
+                $fullName = $repo['full_name'] ?? '';
+
+                if ($fullName !== '') {
+                    $repos[] = $fullName;
+                }
+            }
+
+            $page++;
+        }
+
+        return $repos;
+    }
+
+    /**
+     * Make an HTTP request to the Gitea API.
+     */
+    private function apiRequest(
+        string $giteaUrl,
+        string $token,
+        string $method,
+        string $endpoint,
+        ?string $body = null
+    ): array {
+        $url = $giteaUrl . $endpoint;
+
+        $ch = curl_init();
+        curl_setopt($ch, CURLOPT_URL, $url);
+        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
+        curl_setopt($ch, CURLOPT_HTTPHEADER, [
+            'Content-Type: application/json',
+            'Accept: application/json',
+            "Authorization: token {$token}",
+        ]);
+
+        if ($body !== null) {
+            curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+        }
+
+        $responseBody = curl_exec($ch);
+        $httpCode = (int) curl_getinfo(
+            $ch,
+            CURLINFO_HTTP_CODE
+        );
+
+        if (curl_errno($ch)) {
+            $error = curl_error($ch);
+            curl_close($ch);
+
+            return [
+                'code' => 0,
+                'body' => "cURL error: {$error}",
+            ];
+        }
+
+        curl_close($ch);
+
+        return ['code' => $httpCode, 'body' => $responseBody];
+    }
+}
+
+$app = new WorkflowSyncCli();
+exit($app->execute());

deploy/backup-before-deploy.php

@@ -12,7 +12,7 @@
  * INGROUP: MokoPlatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /deploy/backup-before-deploy.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Snapshot Joomla directories before deployment for rollback capability
  */
 

deploy/deploy-dolibarr.php

@@ -12,7 +12,7 @@
  * INGROUP: MokoPlatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /deploy/deploy-dolibarr.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Deploy Dolibarr module files to a remote server via SFTP/rsync
  */
 

deploy/deploy-sftp.php

@@ -21,7 +21,7 @@ require_once __DIR__ . '/../vendor/autoload.php';
 
 require_once __DIR__ . '/../lib/Enterprise/CliFramework.php';
 
-use MokoEnterprise\CliFramework;
+use MokoEnterprise\{CliFramework, SourceResolver};
 use phpseclib3\Net\SFTP;
 use phpseclib3\Crypt\PublicKeyLoader;
 
@@ -51,9 +51,9 @@ class DeploySftp extends CliFramework
 
     protected function configure(): void
     {
-        $this->setDescription('Deploy a repository src/ directory to a remote web server via SFTP');
+        $this->setDescription('Deploy a repository source directory to a remote web server via SFTP');
         $this->addArgument('--path', 'Repository root (default: current directory)', '.');
-        $this->addArgument('--src-dir', 'Source sub-directory to upload (default: src)', 'src');
+        $this->addArgument('--src-dir', 'Source sub-directory to upload (default: auto-detect)', '');
         $this->addArgument('--env', 'Target environment: dev or rs', '');
         $this->addArgument('--config', 'Explicit config file path — overrides --env', '');
         $this->addArgument('--key-passphrase', 'Passphrase for the SSH private key', '');
@@ -158,7 +158,8 @@ class DeploySftp extends CliFramework
      */
     private function resolveSrcDir(string $repoPath): string
     {
-        $sub = $this->getArgument('--src-dir', 'src');
+        $sub = $this->getArgument('--src-dir', '') ?: SourceResolver::resolve($repoPath);
+        SourceResolver::warnIfLegacy($repoPath);
         $dir = $repoPath . DIRECTORY_SEPARATOR . $sub;
 
         if (!is_dir($dir)) {

deploy/health-check.php

@@ -12,7 +12,7 @@
  * INGROUP: MokoPlatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /deploy/health-check.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Post-deploy health check — verify a Joomla site is responding correctly
  */
 

deploy/rollback-joomla.php

@@ -12,7 +12,7 @@
  * INGROUP: MokoPlatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /deploy/rollback-joomla.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Rollback a Joomla deployment by restoring from a pre-deploy snapshot
  */
 

deploy/sync-joomla.php

@@ -12,7 +12,7 @@
  * INGROUP: MokoPlatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /deploy/sync-joomla.php
- * VERSION: 09.25.00
+ * VERSION: 09.25.02
  * BRIEF: Sync Joomla site directories between two servers via rsync over SSH
  */
 

lib/Enterprise/CliFramework.php

@@ -171,6 +171,13 @@ abstract class CliFramework
      */
     public function __construct(string $name = '', string $version = '04.00.15')
     {
+        // Load Composer autoloader for Enterprise classes (SourceResolver, etc.)
+        $autoloader = __DIR__ . '/../../vendor/autoload.php';
+
+        if (file_exists($autoloader)) {
+            require_once $autoloader;
+        }
+
         $this->scriptName    = $name ?: basename($_SERVER['argv'][0] ?? 'script', '.php');
         $this->scriptVersion = $version;
         $this->startTime     = microtime(true);

lib/Enterprise/ManifestReader.php

@@ -147,31 +147,29 @@ class ManifestReader
     /**
      * Get the source/entry-point directory.
      *
+     * Fallback chain: manifest entry-point → source/ → src/ → htdocs/ → 'source'.
+     * Uses SourceResolver for the directory fallback when no entry-point is set.
+     *
      * @param string $root Repository root for existence checking
-     * @return string Resolved source directory path (e.g. 'src', 'htdocs')
+     * @return string Resolved source directory path (e.g. 'source', 'src', 'htdocs')
      */
     public function getSourceDir(string $root = ''): string
     {
         $entryPoint = $this->get('entry-point', '');
         if ($entryPoint !== '') {
-            // Strip trailing filename (e.g. src/index.ts → src)
+            // Strip trailing filename (e.g. source/index.ts → source)
             $dir = rtrim(dirname($entryPoint) === '.' ? $entryPoint : dirname($entryPoint), '/');
             if ($root === '' || is_dir("{$root}/{$dir}")) {
                 return $dir;
             }
         }
 
-        // Fallback: check common directories
+        // Fallback: use SourceResolver (source/ → src/ → htdocs/ → default 'source')
         if ($root !== '') {
-            if (is_dir("{$root}/src")) {
-                return 'src';
-            }
-            if (is_dir("{$root}/htdocs")) {
-                return 'htdocs';
-            }
+            return SourceResolver::resolve($root);
         }
 
-        return 'src';
+        return 'source';
     }
 
     /**

lib/Enterprise/PackageBuilder.php

@@ -68,7 +68,8 @@ class PackageBuilder
         mkdir($packageDir, 0755, true);
         mkdir($distDir, 0755, true);
 
-        foreach (['src', 'admin', 'site'] as $dir) {
+        $srcName = SourceResolver::resolve($repoRoot);
+        foreach ([$srcName, 'admin', 'site'] as $dir) {
             if (is_dir($repoRoot . '/' . $dir)) {
                 self::copyDirectory($repoRoot . '/' . $dir, $packageDir . '/' . $dir);
             }
@@ -94,15 +95,15 @@ class PackageBuilder
     /**
      * Build a Dolibarr module release package.
      *
-     * Copies everything under src/ into a build staging directory and archives
-     * it as dist/<MODULE_NAME>_<VERSION>.zip.
+     * Copies everything under source/ (or src/) into a build staging directory
+     * and archives it as dist/<MODULE_NAME>_<VERSION>.zip.
      *
      * @param string $repoRoot   Absolute path to the repository root.
      * @param string $moduleName Module name (used in archive filename).
      * @param string $version    Version string.
      * @param bool   $dryRun     When true, preview without writing.
      * @return string  Path to the created archive (or would-create path in dry-run).
-     * @throws \RuntimeException  When src/ is absent or archive creation fails.
+     * @throws \RuntimeException  When source directory is absent or archive creation fails.
      */
     public static function buildDolibarr(
         string $repoRoot,
@@ -110,14 +111,15 @@ class PackageBuilder
         string $version,
         bool $dryRun = false
     ): string {
-        $srcDir      = $repoRoot . '/src';
+        $srcDir      = SourceResolver::resolveAbsolute($repoRoot);
         $buildDir    = $repoRoot . '/build';
         $distDir     = $repoRoot . '/dist';
         $archivePath = $distDir . '/' . $moduleName . '_' . $version . '.zip';
 
-        if (!is_dir($srcDir)) {
-            throw new \RuntimeException("src/ directory not found at {$srcDir}");
+        if ($srcDir === null) {
+            throw new \RuntimeException("source/ or src/ directory not found in {$repoRoot}");
         }
+        SourceResolver::warnIfLegacy($repoRoot);
 
         if ($dryRun) {
             return $archivePath;

lib/Enterprise/Plugins/McpServerPlugin.php

@@ -20,6 +20,7 @@ declare(strict_types=1);
 namespace MokoEnterprise\Plugins;
 
 use MokoEnterprise\AbstractProjectPlugin;
+use MokoEnterprise\SourceResolver;
 
 /**
  * MCP Server Project Plugin
@@ -55,10 +56,12 @@ class McpServerPlugin extends AbstractProjectPlugin
         $warnings = [];
 
         // Check for required source files
-        $requiredSrc = ['src/index.ts', 'src/client.ts', 'src/config.ts', 'src/types.ts'];
+        $srcName = SourceResolver::resolve($projectPath);
+        SourceResolver::warnIfLegacy($projectPath);
+        $requiredSrc = ['index.ts', 'client.ts', 'config.ts', 'types.ts'];
         foreach ($requiredSrc as $file) {
-            if (!file_exists("{$projectPath}/{$file}")) {
-                $errors[] = "Missing required source file: {$file}";
+            if (SourceResolver::findUnderSource($projectPath, $file) === null) {
+                $errors[] = "Missing required source file: {$srcName}/{$file}";
             }
         }
 
@@ -82,37 +85,33 @@ class McpServerPlugin extends AbstractProjectPlugin
             $errors[] = 'Missing tsconfig.json';
         }
 
-        // Check for setup wizard
-        if (!file_exists("{$projectPath}/scripts/setup.mjs")) {
-            $warnings[] = 'Missing scripts/setup.mjs — interactive setup wizard recommended';
-        }
-
         // Check for config example
         if (!file_exists("{$projectPath}/config.example.json")) {
             $warnings[] = 'Missing config.example.json — example configuration recommended';
         }
 
         // Check for shebang in index.ts
-        if (file_exists("{$projectPath}/src/index.ts")) {
-            $content = @file_get_contents("{$projectPath}/src/index.ts");
+        $indexTs = SourceResolver::findUnderSource($projectPath, 'index.ts');
+        if ($indexTs !== null) {
+            $content = @file_get_contents($indexTs);
             if ($content && strpos($content, '#!/usr/bin/env node') === false) {
-                $warnings[] = 'src/index.ts should start with #!/usr/bin/env node shebang';
+                $warnings[] = "{$srcName}/index.ts should start with #!/usr/bin/env node shebang";
             }
         }
 
         // Check for McpServer usage
-        if (file_exists("{$projectPath}/src/index.ts")) {
-            $content = @file_get_contents("{$projectPath}/src/index.ts");
+        if ($indexTs !== null) {
+            $content = $content ?? @file_get_contents($indexTs);
             if ($content && strpos($content, 'McpServer') === false) {
-                $errors[] = 'src/index.ts must import and use McpServer from @modelcontextprotocol/sdk';
+                $errors[] = "{$srcName}/index.ts must import and use McpServer from @modelcontextprotocol/sdk";
             }
         }
 
         // Check for StdioServerTransport
-        if (file_exists("{$projectPath}/src/index.ts")) {
-            $content = @file_get_contents("{$projectPath}/src/index.ts");
+        if ($indexTs !== null) {
+            $content = $content ?? @file_get_contents($indexTs);
             if ($content && strpos($content, 'StdioServerTransport') === false) {
-                $warnings[] = 'src/index.ts should use StdioServerTransport for Claude Code compatibility';
+                $warnings[] = "{$srcName}/index.ts should use StdioServerTransport for Claude Code compatibility";
             }
         }
 
@@ -190,12 +189,13 @@ class McpServerPlugin extends AbstractProjectPlugin
         $score = 100;
 
         // Check for required source files
-        $requiredSrc = ['src/index.ts', 'src/client.ts', 'src/config.ts', 'src/types.ts'];
+        $srcName = SourceResolver::resolve($projectPath);
+        $requiredSrc = ['index.ts', 'client.ts', 'config.ts', 'types.ts'];
         foreach ($requiredSrc as $file) {
-            if (!file_exists("{$projectPath}/{$file}")) {
+            if (SourceResolver::findUnderSource($projectPath, $file) === null) {
                 $issues[] = [
                     'severity' => 'critical',
-                    'message' => "Missing required file: {$file}",
+                    'message' => "Missing required file: {$srcName}/{$file}",
                 ];
                 $score -= 20;
             }
@@ -214,14 +214,15 @@ class McpServerPlugin extends AbstractProjectPlugin
         }
 
         // Check for at least one registered tool
-        if (file_exists("{$projectPath}/src/index.ts")) {
-            $content = @file_get_contents("{$projectPath}/src/index.ts");
+        $indexTs = SourceResolver::findUnderSource($projectPath, 'index.ts');
+        if ($indexTs !== null) {
+            $content = @file_get_contents($indexTs);
             if ($content) {
                 $toolCount = substr_count($content, 'server.tool(');
                 if ($toolCount === 0) {
                     $issues[] = [
                         'severity' => 'critical',
-                        'message' => 'No MCP tools registered in src/index.ts',
+                        'message' => "No MCP tools registered in {$srcName}/index.ts",
                     ];
                     $score -= 25;
                 } elseif ($toolCount < 5) {

lib/Enterprise/RepositorySynchronizer.php

@@ -173,37 +173,15 @@ class RepositorySynchronizer
         $platform = $this->detectPlatform($repoInfo);
         $this->logger->logInfo("Detected platform for {$repo}: {$platform}");
 
-        // Load file list from the Terraform definition for this platform
-        $filesToSync = $this->definitionParser->parseForPlatform($platform, $repoRoot);
-
-        // Append shared workflows — the parser can't extract them from nested
-        // subdirectories blocks due to heredoc interference in .tf files.
-        $sharedFiles = $this->getSharedWorkflows($platform, $repoRoot);
-
-        // Deduplicate by destination — shared workflows take precedence over parser entries
-        $seen = [];
-        foreach ($filesToSync as $f) {
-            $seen[$f['destination']] = true;
-        }
-        foreach ($sharedFiles as $f) {
-            if (!isset($seen[$f['destination']])) {
-                $filesToSync[] = $f;
-            }
-        }
-
-        $defCount = count($filesToSync) - count($sharedFiles);
-        $sharedAdded = count($filesToSync) - $defCount;
-        $sharedTotal = count($sharedFiles);
+        // Load shared workflows and config files for this platform from templates
+        $filesToSync = $this->getSharedWorkflows($platform, $repoRoot);
+        $sharedTotal = count($filesToSync);
         $this->logger->logInfo(
-            "Loaded " . count($filesToSync) . " sync entries for {$platform}"
-            . " (def={$defCount}, shared={$sharedAdded}/{$sharedTotal} added, "
-            . ($sharedTotal - $sharedAdded) . " deduped)"
+            "Loaded {$sharedTotal} sync entries for {$platform}"
         );
-        // Log shared workflow destinations for debugging
-        foreach ($sharedFiles as $sf) {
+        foreach ($filesToSync as $sf) {
             $dest = $sf['destination'] ?? '?';
-            $added = !isset($seen[$dest]) ? 'ADDED' : 'DEDUPED';
-            $this->logger->logInfo("  shared: {$dest} [{$added}]");
+            $this->logger->logInfo("  sync: {$dest}");
         }
 
         if (empty($filesToSync)) {
@@ -1380,7 +1358,7 @@ class RepositorySynchronizer
 
             $descriptors = array_values(array_filter(
                 $paths,
-                static fn(string $p): bool => (bool) preg_match('#src/core/modules/mod\w+\.class\.php$#', $p)
+                static fn(string $p): bool => (bool) preg_match('#(?:source|src)/core/modules/mod\w+\.class\.php$#', $p)
             ));
 
             if (empty($descriptors)) {

lib/Enterprise/SourceResolver.php

@@ -0,0 +1,187 @@
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: MokoPlatform.Enterprise
+ * INGROUP: MokoPlatform.Lib
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+ * PATH: /lib/Enterprise/SourceResolver.php
+ * BRIEF: Resolve the root-level source directory across repos (source/, src/, htdocs/)
+ */
+
+declare(strict_types=1);
+
+namespace MokoEnterprise;
+
+/**
+ * Source Directory Resolver
+ *
+ * Provides a single, consistent fallback chain for locating the root-level
+ * source directory in any MokoStandards repository. The preferred directory
+ * is `source/`, with legacy `src/` and `htdocs/` as fallbacks.
+ *
+ * This class exists because Joomla extensions use `src/` for namespace
+ * autoloading (e.g. administrator/components/com_foo/src/). Renaming our
+ * root-level source directory to `source/` avoids that collision. During
+ * the transition period, repos may still use `src/`, so all tooling must
+ * check both.
+ *
+ * Usage:
+ *   $dir  = SourceResolver::resolve($repoRoot);          // 'source', 'src', or 'htdocs'
+ *   $abs  = SourceResolver::resolveAbsolute($repoRoot);   // full path or null
+ *   $xmls = SourceResolver::globSource($repoRoot, '*.xml'); // glob under first match
+ *   $path = SourceResolver::findUnderSource($repoRoot, 'core/modules'); // subpath lookup
+ *
+ * @since 09.02.00
+ */
+class SourceResolver
+{
+    /**
+     * Ordered candidate directories. source/ is preferred, src/ is legacy fallback.
+     *
+     * When the migration is complete and all repos use source/, the 'src'
+     * entry can be removed from this list.
+     *
+     * @var string[]
+     */
+    private const CANDIDATES = ['source', 'src', 'htdocs'];
+
+    /**
+     * Resolve the source directory name for a repository root.
+     *
+     * Returns the first candidate directory that exists, or 'source' as the
+     * default when no candidate is found (e.g. for new repos being scaffolded).
+     *
+     * @param string $root Absolute path to the repository root.
+     * @return string Directory name (e.g. 'source', 'src', 'htdocs').
+     */
+    public static function resolve(string $root): string
+    {
+        foreach (self::CANDIDATES as $candidate) {
+            if (is_dir("{$root}/{$candidate}")) {
+                return $candidate;
+            }
+        }
+
+        return 'source';
+    }
+
+    /**
+     * Resolve the source directory as an absolute path.
+     *
+     * @param string $root Absolute path to the repository root.
+     * @return string|null Absolute path to the source directory, or null if none exists.
+     */
+    public static function resolveAbsolute(string $root): ?string
+    {
+        foreach (self::CANDIDATES as $candidate) {
+            $path = "{$root}/{$candidate}";
+            if (is_dir($path)) {
+                return $path;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Glob for files under the source directory.
+     *
+     * Checks each candidate directory in order and returns matches from the
+     * first candidate that produces results. This replaces patterns like:
+     *
+     *   glob("{$root}/src/*.xml")
+     *
+     * With the backwards-compatible:
+     *
+     *   SourceResolver::globSource($root, '*.xml')
+     *
+     * @param string $root    Absolute path to the repository root.
+     * @param string $pattern Glob pattern relative to the source directory.
+     * @return string[] Matched file paths (may be empty).
+     */
+    public static function globSource(string $root, string $pattern): array
+    {
+        foreach (self::CANDIDATES as $candidate) {
+            $dir = "{$root}/{$candidate}";
+            if (!is_dir($dir)) {
+                continue;
+            }
+            $matches = glob("{$dir}/{$pattern}") ?: [];
+            if ($matches !== []) {
+                return $matches;
+            }
+        }
+
+        return [];
+    }
+
+    /**
+     * Find a subpath under any source directory candidate.
+     *
+     * Useful for locating platform-specific subdirectories like
+     * `core/modules/` (Dolibarr) or `media/templates/` (Joomla client themes)
+     * regardless of whether the repo uses `source/` or `src/`.
+     *
+     * @param string $root    Absolute path to the repository root.
+     * @param string $subpath Relative path to look for (e.g. 'core/modules', 'index.ts').
+     * @return string|null    Absolute path if found, null otherwise.
+     */
+    public static function findUnderSource(string $root, string $subpath): ?string
+    {
+        foreach (self::CANDIDATES as $candidate) {
+            $full = "{$root}/{$candidate}/{$subpath}";
+            if (file_exists($full) || is_dir($full)) {
+                return $full;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Get the ordered list of candidate directory names.
+     *
+     * Useful for workflows or scripts that need to iterate candidates
+     * themselves (e.g. building find/grep patterns).
+     *
+     * @return string[]
+     */
+    public static function getCandidates(): array
+    {
+        return self::CANDIDATES;
+    }
+
+    /**
+     * Check whether the resolved source directory is a legacy name (src/).
+     *
+     * @param string $root Absolute path to the repository root.
+     * @return bool True if the repo uses src/ instead of source/.
+     */
+    public static function isLegacy(string $root): bool
+    {
+        $resolved = self::resolve($root);
+
+        return $resolved === 'src';
+    }
+
+    /**
+     * Emit a deprecation warning to stderr if the repo still uses src/.
+     *
+     * CLI tools should call this after resolving the source directory so
+     * that maintainers know to rename src/ → source/.
+     *
+     * @param string $root Absolute path to the repository root.
+     */
+    public static function warnIfLegacy(string $root): void
+    {
+        if (self::isLegacy($root)) {
+            fwrite(STDERR, "⚠  WARNING: This repo uses src/ which is deprecated. Rename to source/ per MokoStandards.\n");
+        }
+    }
+}

mcp/servers/mokobackup/.mokogitea/CLAUDE.md

@@ -0,0 +1,49 @@
+# mcp_mokobackup
+
+MCP server for database and file backups across Dolibarr, Joomla/Akeeba, Gitea, and file-based environments.
+
+## Quick Reference
+
+| Field | Value |
+|---|---|
+| **Package** | `@mokoconsulting/backup-mcp` |
+| **Entry** | `dist/index.js` |
+| **Config** | `~/.mcp_mokobackup.json` (override: `BACKUP_MCP_CONFIG` env var) |
+| **Language** | TypeScript |
+| **Branch** | develop on `dev`, merge to `main` (protected) |
+
+## Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript → dist/
+npm run dev          # Watch mode
+```
+
+## Architecture
+
+```
+src/
+├── index.ts         # MCP server entry, tool registration
+├── config.ts        # Loads ~/.mcp_mokobackup.json, resolves targets
+├── client.ts        # Backup execution logic
+├── akeeba.ts        # Akeeba Backup API integration (Joomla sites)
+├── mokobackup.ts    # MokoJoomBackup REST API integration
+└── types.ts         # BackupConfig, BackupTarget types
+```
+
+- Config defines **targets** — each target has a type (akeeba, dolibarr, mysql, files, gitea-db, gitea-files)
+- Client-specific targets go in client repo configs, not global
+- Dolibarr backups read `conf.php` via SSH to get DB credentials
+
+## Config
+
+Default config at `~/.mcp_mokobackup.json`. Client repos override via `BACKUP_MCP_CONFIG` env var pointing to their own config file (e.g. `A:/client-clarksvillefurs/.mcp_mokobackup.json`).
+
+## Rules
+
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
+- **Attribution**: `Authored-by: Moko Consulting`
+- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
+- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)

mcp/servers/mokobackup/.mokogitea/workflows/pr-check.yml

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

mcp/servers/mokobackup/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [1.0] — 2026-05-08
+
+### Added
+- Initial release

mcp/servers/mokobackup/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+See [standards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki).

mcp/servers/mokobackup/README.md

@@ -0,0 +1,76 @@
+# backup-mcp
+
+MCP server for database and file backups across Dolibarr and Joomla environments
+
+![Language](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-backup-mcp-blue?style=flat-square)
+
+
+Model Context Protocol server for database dumps, file backups, and Akeeba Backup integration on Joomla sites.
+
+---
+
+| | |
+|---|---|
+| **Type** | MCP Server |
+| **Language** | Node.js |
+| **Tools** | 11 tools (6 SSH-based + 5 Akeeba API) |
+| **License** | GPL-3.0-or-later |
+| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp) (primary) |
+
+---
+
+## Overview
+
+backup-mcp provides two backup strategies through a single MCP server:
+
+| Strategy | Method | Tools |
+|----------|--------|-------|
+| **SSH Backups** | MySQL/PostgreSQL dumps and tar archives via SSH | `backup_database`, `backup_files`, `backup_list`, `backup_prune`, `backup_status`, `backup_list_targets` |
+| **Akeeba Backups** | Joomla Web Services API (`/api/index.php/v1/akeebabackup/*`) | `akeeba_backup`, `akeeba_list`, `akeeba_download`, `akeeba_delete`, `akeeba_profiles` |
+
+Each client repo has its own `.backup-mcp.json` scoped via the `BACKUP_MCP_CONFIG` env var in `.mcp.json`.
+
+---
+
+## Wiki Pages
+
+### Reference
+
+- [Tools Reference](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp/wiki/Tools-Reference) -- all 11 tools with descriptions
+- [Akeeba Integration](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp/wiki/Akeeba-Integration) -- Akeeba Backup Pro setup, requirements, per-client workspace config
+
+---
+
+## Related Wikis
+
+| Repo | Purpose |
+|------|---------|
+| [ssh-mcp](https://git.mokoconsulting.tech/MokoConsulting/ssh-mcp/wiki) | SSH server management (used for SSH-based backups) |
+| [joomla-api-mcp](https://git.mokoconsulting.tech/MokoConsulting/joomla-api-mcp/wiki) | Joomla Web Services API MCP |
+| [deploy-mcp](https://git.mokoconsulting.tech/MokoConsulting/deploy-mcp/wiki) | Git-based deployment MCP |
+
+---
+
+> **[MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki)** -- central standards hub for all Moko Consulting projects.
+
+---
+
+
+
+---
+
+## Documentation
+
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/backup-mcp/wiki).
+
+## Contributing
+
+See the wiki for development guidelines and contribution instructions.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.
+
+---
+
+*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

mcp/servers/mokobackup/SECURITY.md

@@ -0,0 +1,3 @@
+# Security
+
+Report to hello@mokoconsulting.tech.

mcp/servers/mokobackup/config.example.json

@@ -0,0 +1,28 @@
+{
+	"defaultTarget": "dolibarr-db",
+	"targets": {
+		"dolibarr-db": {
+			"name": "dolibarr",
+			"type": "mysql",
+			"sshHost": "crm.mokoconsulting.tech",
+			"sshUser": "mokoconsulting",
+			"sshKeyPath": "~/.ssh/id_ed25519",
+			"database": "dolibarr",
+			"dbUser": "dolibarr",
+			"dbPassword": "your-db-password",
+			"localBackupDir": "~/backups/dolibarr"
+		},
+		"joomla-db": {
+			"name": "joomla",
+			"type": "mysql",
+			"sshHost": "waas.mokoconsulting.tech",
+			"sshUser": "mokoconsulting",
+			"sshKeyPath": "~/.ssh/id_ed25519",
+			"database": "joomla",
+			"dbUser": "joomla",
+			"dbPassword": "your-db-password",
+			"remotePaths": ["/var/www/html/images", "/var/www/html/media"],
+			"localBackupDir": "~/backups/joomla"
+		}
+	}
+}

mcp/servers/mokobackup/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@mokoconsulting/backup-mcp",
+	"version": "1.0.0",
+	"description": "MCP server for database and file backups across Dolibarr and Joomla environments",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": { "backup-mcp": "dist/index.js" },
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"start": "node dist/index.js",
+		"clean": "rm -rf dist/"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.1",
+		"zod": "^3.24.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.3",
+		"typescript": "^5.8.3"
+	},
+	"engines": { "node": ">=20.0.0" },
+	"license": "GPL-3.0-or-later",
+	"author": "Moko Consulting <hello@mokoconsulting.tech>"
+}

mcp/servers/mokobackup/src/akeeba.ts

@@ -0,0 +1,129 @@
+import * as https from 'node:https';
+import * as http from 'node:http';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BackupTarget, BackupResult, AkeebaBackupRecord } from './types.js';
+
+const TIMEOUT_MS = 300_000; // 5 min for backup operations
+
+/**
+ * Akeeba Backup client using Joomla Web Services API
+ * Endpoint: /api/index.php/v1/akeebabackup/*
+ * Auth: Bearer token (Joomla API token)
+ */
+export class AkeebaClient {
+	private readonly target: BackupTarget;
+	private readonly baseUrl: string;
+	private readonly headers: Record<string, string>;
+
+	constructor(target: BackupTarget) {
+		this.target = target;
+		const site = (target.siteUrl ?? '').replace(/\/+$/, '');
+		this.baseUrl = `${site}/api/index.php/v1/akeebabackup`;
+		this.headers = {
+			'Authorization': `Bearer ${target.secretWord}`,
+			'Content-Type': 'application/json',
+			'Accept': 'application/vnd.api+json',
+		};
+	}
+
+	private request(url: string, method: string, body?: unknown): Promise<{ status: number; data: unknown }> {
+		return new Promise((resolve, reject) => {
+			const parsed = new URL(url);
+			const mod = parsed.protocol === 'https:' ? https : http;
+			const payload = body ? JSON.stringify(body) : undefined;
+			const opts: http.RequestOptions = {
+				hostname: parsed.hostname,
+				port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+				path: parsed.pathname + parsed.search,
+				method,
+				headers: { ...this.headers, ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}) },
+				timeout: TIMEOUT_MS,
+			};
+
+			const req = mod.request(opts, (res) => {
+				const chunks: Buffer[] = [];
+				res.on('data', (c: Buffer) => chunks.push(c));
+				res.on('end', () => {
+					const raw = Buffer.concat(chunks).toString();
+					let data: unknown;
+					try { data = JSON.parse(raw); } catch { data = raw; }
+					resolve({ status: res.statusCode ?? 0, data });
+				});
+			});
+			req.on('error', reject);
+			req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+			if (payload) req.write(payload);
+			req.end();
+		});
+	}
+
+	async startBackup(profileId?: number, description?: string): Promise<BackupResult> {
+		try {
+			const profile = profileId ?? this.target.profileId ?? 1;
+			const desc = description ?? `MCP backup ${new Date().toISOString()}`;
+			const res = await this.request(`${this.baseUrl}/backup`, 'POST', {
+				profile: profile,
+				description: desc,
+			});
+
+			if (res.status >= 400) {
+				return { success: false, message: `Akeeba backup failed: ${JSON.stringify(res.data)}` };
+			}
+
+			return { success: true, message: `Akeeba backup started (profile ${profile}): ${desc}` };
+		} catch (err) {
+			return { success: false, message: `Akeeba backup failed: ${err}` };
+		}
+	}
+
+	async listBackups(limit = 20): Promise<AkeebaBackupRecord[]> {
+		try {
+			const res = await this.request(`${this.baseUrl}/backups?page[limit]=${limit}`, 'GET');
+			if (res.status >= 400) return [];
+			const body = res.data as { data?: Array<{ attributes: AkeebaBackupRecord }> };
+			return (body.data ?? []).map(d => d.attributes);
+		} catch { return []; }
+	}
+
+	async deleteBackup(id: string): Promise<BackupResult> {
+		try {
+			const res = await this.request(`${this.baseUrl}/backup/${id}`, 'DELETE');
+			if (res.status >= 400) return { success: false, message: `Delete failed: ${JSON.stringify(res.data)}` };
+			return { success: true, message: `Deleted Akeeba backup ${id}` };
+		} catch (err) {
+			return { success: false, message: `Delete failed: ${err}` };
+		}
+	}
+
+	async downloadBackup(id: string): Promise<BackupResult> {
+		try {
+			mkdirSync(this.target.localBackupDir, { recursive: true });
+			const res = await this.request(`${this.baseUrl}/backup/${id}/download`, 'GET');
+
+			if (res.status >= 400) {
+				return { success: false, message: `Download failed: ${JSON.stringify(res.data)}` };
+			}
+
+			const filename = `${this.target.name}-akeeba-${id}-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.jpa`;
+			const localFile = join(this.target.localBackupDir, filename);
+			const fs = await import('node:fs/promises');
+
+			if (typeof res.data === 'string') {
+				const buffer = Buffer.from(res.data, 'base64');
+				await fs.writeFile(localFile, buffer);
+				return { success: true, message: `Downloaded backup ${id}`, filePath: localFile, sizeBytes: buffer.length };
+			}
+
+			await fs.writeFile(localFile, JSON.stringify(res.data));
+			return { success: true, message: `Downloaded backup ${id}`, filePath: localFile };
+		} catch (err) {
+			return { success: false, message: `Download failed: ${err}` };
+		}
+	}
+
+	async getProfiles(): Promise<unknown> {
+		const res = await this.request(`${this.baseUrl}/profiles`, 'GET');
+		return res.data;
+	}
+}

mcp/servers/mokobackup/src/client.ts

@@ -0,0 +1,141 @@
+// Uses execFile (safe, no shell interpolation) for all SSH/command execution
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BackupTarget, BackupResult } from './types.js';
+
+const execFile = promisify(execFileCb);
+const TIMEOUT = 300_000; // 5 min for large backups
+
+export class BackupClient {
+	private readonly target: BackupTarget;
+
+	constructor(target: BackupTarget) {
+		this.target = target;
+		mkdirSync(target.localBackupDir, { recursive: true });
+	}
+
+	private sshArgs(cmd: string): string[] {
+		const args = ['-o', 'StrictHostKeyChecking=accept-new', '-o', 'BatchMode=yes'];
+		if (this.target.sshPort) args.push('-p', String(this.target.sshPort));
+		if (this.target.sshKeyPath) args.push('-i', this.target.sshKeyPath);
+		args.push(`${this.target.sshUser}@${this.target.sshHost}`, cmd);
+		return args;
+	}
+
+	private timestamp(): string {
+		return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+	}
+
+	async dumpDatabase(): Promise<BackupResult> {
+		const ts = this.timestamp();
+		const filename = `${this.target.name}-db-${ts}.sql.gz`;
+		const localFile = join(this.target.localBackupDir, filename);
+		const dumpCmd = this.target.type === 'mysql'
+			? `mysqldump -u ${this.target.dbUser} -p'${this.target.dbPassword}' ${this.target.database} | gzip`
+			: `PGPASSWORD='${this.target.dbPassword}' pg_dump -U ${this.target.dbUser} ${this.target.database} | gzip`;
+
+		try {
+			const { stdout } = await execFile('ssh', this.sshArgs(dumpCmd), { timeout: TIMEOUT, maxBuffer: 500 * 1024 * 1024 });
+			const fs = await import('node:fs/promises');
+			await fs.writeFile(localFile, stdout, 'binary');
+			const stat = statSync(localFile);
+			return { success: true, message: `Database backup: ${filename}`, filePath: localFile, sizeBytes: stat.size };
+		} catch (err) {
+			return { success: false, message: `Database backup failed: ${err}` };
+		}
+	}
+
+	async backupFiles(): Promise<BackupResult> {
+		const ts = this.timestamp();
+		const filename = `${this.target.name}-files-${ts}.tar.gz`;
+		const localFile = join(this.target.localBackupDir, filename);
+		const paths = (this.target.remotePaths ?? []).join(' ');
+		const tarCmd = `tar czf - ${paths}`;
+
+		try {
+			const { stdout } = await execFile('ssh', this.sshArgs(tarCmd), { timeout: TIMEOUT, maxBuffer: 500 * 1024 * 1024 });
+			const fs = await import('node:fs/promises');
+			await fs.writeFile(localFile, stdout, 'binary');
+			const stat = statSync(localFile);
+			return { success: true, message: `File backup: ${filename}`, filePath: localFile, sizeBytes: stat.size };
+		} catch (err) {
+			return { success: false, message: `File backup failed: ${err}` };
+		}
+	}
+
+	listBackups(): { name: string; size: number; date: Date }[] {
+		try {
+			return readdirSync(this.target.localBackupDir)
+				.filter(f => f.startsWith(this.target.name))
+				.map(f => {
+					const stat = statSync(join(this.target.localBackupDir, f));
+					return { name: f, size: stat.size, date: stat.mtime };
+				})
+				.sort((a, b) => b.date.getTime() - a.date.getTime());
+		} catch { return []; }
+	}
+
+	async parseDolibarrConf(): Promise<{ dbHost: string; dbName: string; dbUser: string; dbPass: string; dataRoot: string }> {
+		const confPath = this.target.confPath ?? '/htdocs/conf/conf.php';
+		const cmd = `cat ${confPath}`;
+		const { stdout } = await execFile('ssh', this.sshArgs(cmd), { timeout: TIMEOUT });
+		const get = (key: string) => {
+			const m = stdout.match(new RegExp(`\\$${key}\\s*=\\s*['"]([^'"]*)`));
+			if (!m) throw new Error(`Could not find $${key} in ${confPath}`);
+			return m[1];
+		};
+		return {
+			dbHost: get('dolibarr_main_db_host'),
+			dbName: get('dolibarr_main_db_name'),
+			dbUser: get('dolibarr_main_db_user'),
+			dbPass: get('dolibarr_main_db_pass'),
+			dataRoot: get('dolibarr_main_data_root'),
+		};
+	}
+
+	async dumpDolibarr(): Promise<BackupResult> {
+		const ts = this.timestamp();
+		const conf = await this.parseDolibarrConf();
+
+		// 1. Database dump
+		const dbFilename = `${this.target.name}-db-${ts}.sql.gz`;
+		const dbLocalFile = join(this.target.localBackupDir, dbFilename);
+		const dumpCmd = `mysqldump -h ${conf.dbHost} -u ${conf.dbUser} -p'${conf.dbPass}' ${conf.dbName} | gzip`;
+		try {
+			const { stdout: dbOut } = await execFile('ssh', this.sshArgs(dumpCmd), { timeout: TIMEOUT, maxBuffer: 500 * 1024 * 1024 });
+			const fs = await import('node:fs/promises');
+			await fs.writeFile(dbLocalFile, dbOut, 'binary');
+
+			// 2. Documents + custom directories
+			const filesFilename = `${this.target.name}-files-${ts}.tar.gz`;
+			const filesLocalFile = join(this.target.localBackupDir, filesFilename);
+			const customDir = conf.dataRoot.replace(/\/documents\/?$/, '/custom');
+			const tarCmd = `tar czf - ${conf.dataRoot} ${customDir} 2>/dev/null`;
+			const { stdout: tarOut } = await execFile('ssh', this.sshArgs(tarCmd), { timeout: TIMEOUT, maxBuffer: 500 * 1024 * 1024 });
+			await fs.writeFile(filesLocalFile, tarOut, 'binary');
+
+			const dbStat = statSync(dbLocalFile);
+			const filesStat = statSync(filesLocalFile);
+			return {
+				success: true,
+				message: `Dolibarr backup complete:\n  DB: ${dbFilename} (${(dbStat.size / 1024 / 1024).toFixed(1)} MB)\n  Files: ${filesFilename} (${(filesStat.size / 1024 / 1024).toFixed(1)} MB)`,
+				filePath: dbLocalFile,
+				sizeBytes: dbStat.size + filesStat.size,
+			};
+		} catch (err) {
+			return { success: false, message: `Dolibarr backup failed: ${err}` };
+		}
+	}
+
+	async pruneBackups(olderThanDays: number): Promise<BackupResult> {
+		const cutoff = Date.now() - olderThanDays * 86400000;
+		const fs = await import('node:fs/promises');
+		const backups = this.listBackups().filter(b => b.date.getTime() < cutoff);
+		for (const b of backups) {
+			await fs.unlink(join(this.target.localBackupDir, b.name));
+		}
+		return { success: true, message: `Pruned ${backups.length} backups older than ${olderThanDays} days` };
+	}
+}

mcp/servers/mokobackup/src/config.ts

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { BackupConfig, BackupTarget } from './types.js';
+
+const CONFIG_FILENAME = '.mcp_mokobackup.json';
+
+export async function loadConfig(): Promise<BackupConfig> {
+	const configPath = process.env.BACKUP_MCP_CONFIG
+		? resolve(process.env.BACKUP_MCP_CONFIG)
+		: resolve(homedir(), CONFIG_FILENAME);
+
+	const raw = await readFile(configPath, 'utf-8');
+	const parsed = JSON.parse(raw) as Partial<BackupConfig>;
+	if (!parsed.targets || Object.keys(parsed.targets).length === 0) {
+		throw new Error(`No targets in ${configPath}`);
+	}
+	return {
+		targets: parsed.targets,
+		defaultTarget: parsed.defaultTarget ?? Object.keys(parsed.targets)[0],
+	};
+}
+
+export function getTarget(config: BackupConfig, name?: string): BackupTarget {
+	const key = name ?? config.defaultTarget;
+	const target = config.targets[key];
+	if (!target) throw new Error(`Target "${key}" not found. Available: ${Object.keys(config.targets).join(', ')}`);
+	return target;
+}

mcp/servers/mokobackup/src/index.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { loadConfig, getTarget } from './config.js';
+import { BackupClient } from './client.js';
+import { AkeebaClient } from './akeeba.js';
+import { MokoBackupClient } from './mokobackup.js';
+import type { BackupConfig } from './types.js';
+
+let config: BackupConfig;
+
+function clientFor(t?: string): BackupClient { return new BackupClient(getTarget(config, t)); }
+
+/**
+ * Return the appropriate Joomla backup client based on target type.
+ * MokoBackup and Akeeba have the same interface — auto-detect which to use.
+ */
+function joomlaBackupFor(t?: string): AkeebaClient | MokoBackupClient {
+	const target = getTarget(config, t);
+	if (target.type === 'mokobackup') return new MokoBackupClient(target);
+	return new AkeebaClient(target);
+}
+
+// Keep legacy function for backwards compatibility
+function akeebaFor(t?: string): AkeebaClient | MokoBackupClient { return joomlaBackupFor(t); }
+function text(s: string) { return { content: [{ type: 'text' as const, text: s }] }; }
+
+const T = { target: z.string().optional().describe('Backup target name') };
+
+const server = new McpServer({ name: 'backup-mcp', version: '1.0.0' });
+
+// ── SSH-based backups ────────────────────────────────────────────────
+
+server.tool('backup_database', 'Dump database (MySQL/PostgreSQL) to local backup via SSH', { ...T },
+	async ({ target }) => { const r = await clientFor(target).dumpDatabase(); return text(JSON.stringify(r, null, 2)); });
+
+server.tool('backup_files', 'Backup remote directories to local tar.gz via SSH', { ...T },
+	async ({ target }) => { const r = await clientFor(target).backupFiles(); return text(JSON.stringify(r, null, 2)); });
+
+server.tool('backup_list', 'List available local backups with sizes and dates', { ...T },
+	async ({ target }) => {
+		const backups = clientFor(target).listBackups();
+		if (backups.length === 0) return text('No backups found');
+		return text(backups.map(b => `${b.name}  ${(b.size / 1024 / 1024).toFixed(1)} MB  ${b.date.toISOString()}`).join('\n'));
+	});
+
+server.tool('backup_prune', 'Delete local backups older than specified days', {
+	...T, days: z.number().describe('Delete backups older than this many days'),
+}, async ({ target, days }) => { const r = await clientFor(target).pruneBackups(days); return text(r.message); });
+
+server.tool('backup_status', 'Show backup disk usage and last backup info', { ...T },
+	async ({ target }) => {
+		const backups = clientFor(target).listBackups();
+		const totalMB = backups.reduce((s, b) => s + b.size, 0) / 1024 / 1024;
+		const last = backups[0];
+		return text(`Backups: ${backups.length}\nTotal size: ${totalMB.toFixed(1)} MB\nLast backup: ${last ? `${last.name} (${last.date.toISOString()})` : 'none'}`);
+	});
+
+// ── Akeeba Backup (Joomla sites) ─────────────────────────────────────
+
+server.tool('akeeba_backup', 'Start a backup on a Joomla site (Akeeba or MokoBackup — auto-detected by target type)', {
+	...T, description: z.string().optional().describe('Backup description'),
+}, async ({ target, description }) => {
+	const r = await akeebaFor(target).startBackup(undefined, description);
+	return text(JSON.stringify(r, null, 2));
+});
+
+server.tool('akeeba_list', 'List backup records on a Joomla site (Akeeba or MokoBackup)', {
+	...T, limit: z.number().optional().describe('Number of records (default 20)'),
+}, async ({ target, limit }) => {
+	const records = await akeebaFor(target).listBackups(limit ?? 20);
+	if (records.length === 0) return text('No backups found');
+	return text(records.map(r =>
+		`#${r.id}  ${r.status}  ${r.description}  ${r.backupstart}  ${r.archivename}  ${(r.total_size / 1024 / 1024).toFixed(1)} MB`
+	).join('\n'));
+});
+
+server.tool('akeeba_download', 'Download a backup archive from a Joomla site (Akeeba or MokoBackup)', {
+	...T, backup_id: z.string().describe('Backup record ID'),
+}, async ({ target, backup_id }) => {
+	const r = await akeebaFor(target).downloadBackup(backup_id);
+	return text(JSON.stringify(r, null, 2));
+});
+
+server.tool('akeeba_delete', 'Delete a backup record from a Joomla site (Akeeba or MokoBackup)', {
+	...T, backup_id: z.string().describe('Backup record ID'),
+}, async ({ target, backup_id }) => {
+	const r = await akeebaFor(target).deleteBackup(backup_id);
+	return text(r.message);
+});
+
+server.tool('akeeba_profiles', 'List backup profiles on a Joomla site (Akeeba or MokoBackup)', { ...T },
+	async ({ target }) => {
+		const profiles = await akeebaFor(target).getProfiles();
+		return text(JSON.stringify(profiles, null, 2));
+	});
+
+
+// ── Dolibarr Backup ─────────────────────────────────────────────────
+
+server.tool('dolibarr_backup', 'Backup a Dolibarr instance (DB + documents + custom) by reading conf.php via SSH', {
+	...T,
+}, async ({ target }) => {
+	const r = await clientFor(target).dumpDolibarr();
+	return text(JSON.stringify(r, null, 2));
+});
+
+server.tool('dolibarr_conf', 'Read and display Dolibarr database settings from conf.php via SSH (no passwords shown)', {
+	...T,
+}, async ({ target }) => {
+	const conf = await clientFor(target).parseDolibarrConf();
+	return text(`DB Host: ${conf.dbHost}\nDB Name: ${conf.dbName}\nDB User: ${conf.dbUser}\nData Root: ${conf.dataRoot}`);
+});
+
+// ── General ──────────────────────────────────────────────────────────
+
+server.tool('backup_list_targets', 'List all configured backup targets', {},
+	async () => text(Object.entries(config.targets).map(([k, v]) => {
+		const loc = (v.type === 'akeeba' || v.type === 'mokobackup') ? v.siteUrl : `${v.sshUser}@${v.sshHost}`;
+		return `${k}${k === config.defaultTarget ? ' (default)' : ''}: ${v.type} @ ${loc} → ${v.localBackupDir}`;
+	}).join('\n')));
+
+async function main() {
+	config = await loadConfig();
+	await server.connect(new StdioServerTransport());
+}
+main().catch(err => { console.error(err); process.exit(1); });

mcp/servers/mokobackup/src/mokobackup.ts

@@ -0,0 +1,144 @@
+import * as https from 'node:https';
+import * as http from 'node:http';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BackupTarget, BackupResult, AkeebaBackupRecord } from './types.js';
+
+const TIMEOUT_MS = 300_000; // 5 min for backup operations
+
+/**
+ * MokoJoomBackup client using Joomla Web Services API
+ * Endpoint: /api/index.php/v1/mokobackup/*
+ * Auth: Bearer token (Joomla API token)
+ *
+ * Wire-compatible with AkeebaClient — same interface, different base URL.
+ * The existing akeeba_* MCP tools work with both backends.
+ */
+export class MokoBackupClient {
+	private readonly target: BackupTarget;
+	private readonly baseUrl: string;
+	private readonly headers: Record<string, string>;
+
+	constructor(target: BackupTarget) {
+		this.target = target;
+		const site = (target.siteUrl ?? '').replace(/\/+$/, '');
+		this.baseUrl = `${site}/api/index.php/v1/mokobackup`;
+		this.headers = {
+			'Authorization': `Bearer ${target.secretWord}`,
+			'Content-Type': 'application/json',
+			'Accept': 'application/vnd.api+json',
+		};
+	}
+
+	private request(url: string, method: string, body?: unknown): Promise<{ status: number; data: unknown }> {
+		return new Promise((resolve, reject) => {
+			const parsed = new URL(url);
+			const mod = parsed.protocol === 'https:' ? https : http;
+			const payload = body ? JSON.stringify(body) : undefined;
+			const opts: http.RequestOptions = {
+				hostname: parsed.hostname,
+				port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+				path: parsed.pathname + parsed.search,
+				method,
+				headers: { ...this.headers, ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}) },
+				timeout: TIMEOUT_MS,
+			};
+
+			const req = mod.request(opts, (res) => {
+				const chunks: Buffer[] = [];
+				res.on('data', (c: Buffer) => chunks.push(c));
+				res.on('end', () => {
+					const raw = Buffer.concat(chunks).toString();
+					let data: unknown;
+					try { data = JSON.parse(raw); } catch { data = raw; }
+					resolve({ status: res.statusCode ?? 0, data });
+				});
+			});
+			req.on('error', reject);
+			req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+			if (payload) req.write(payload);
+			req.end();
+		});
+	}
+
+	async startBackup(profileId?: number, description?: string): Promise<BackupResult> {
+		try {
+			const profile = profileId ?? this.target.profileId ?? 1;
+			const desc = description ?? `MCP backup ${new Date().toISOString()}`;
+			const res = await this.request(`${this.baseUrl}/backup`, 'POST', {
+				profile: profile,
+				description: desc,
+			});
+
+			if (res.status >= 400) {
+				return { success: false, message: `MokoBackup failed: ${JSON.stringify(res.data)}` };
+			}
+
+			// MokoBackup returns {data: {success, message, record_id}}
+			const body = res.data as { data?: { success: boolean; message: string } };
+			const msg = body?.data?.message ?? `Backup started (profile ${profile}): ${desc}`;
+
+			return { success: true, message: msg };
+		} catch (err) {
+			return { success: false, message: `MokoBackup failed: ${err}` };
+		}
+	}
+
+	async listBackups(limit = 20): Promise<AkeebaBackupRecord[]> {
+		try {
+			const res = await this.request(`${this.baseUrl}/backups?page[limit]=${limit}`, 'GET');
+			if (res.status >= 400) return [];
+			const body = res.data as { data?: Array<{ attributes: AkeebaBackupRecord }> };
+			return (body.data ?? []).map(d => d.attributes);
+		} catch { return []; }
+	}
+
+	async deleteBackup(id: string): Promise<BackupResult> {
+		try {
+			const res = await this.request(`${this.baseUrl}/backup/${id}`, 'DELETE');
+			if (res.status >= 400) return { success: false, message: `Delete failed: ${JSON.stringify(res.data)}` };
+			return { success: true, message: `Deleted MokoBackup record ${id}` };
+		} catch (err) {
+			return { success: false, message: `Delete failed: ${err}` };
+		}
+	}
+
+	async downloadBackup(id: string): Promise<BackupResult> {
+		try {
+			mkdirSync(this.target.localBackupDir, { recursive: true });
+			const res = await this.request(`${this.baseUrl}/backup/${id}/download`, 'GET');
+
+			if (res.status >= 400) {
+				return { success: false, message: `Download failed: ${JSON.stringify(res.data)}` };
+			}
+
+			const filename = `${this.target.name}-mokobackup-${id}-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.zip`;
+			const localFile = join(this.target.localBackupDir, filename);
+			const fs = await import('node:fs/promises');
+
+			if (typeof res.data === 'string') {
+				const buffer = Buffer.from(res.data, 'base64');
+				await fs.writeFile(localFile, buffer);
+				return { success: true, message: `Downloaded backup ${id}`, filePath: localFile, sizeBytes: buffer.length };
+			}
+
+			// Handle JSON-wrapped response
+			const body = res.data as { data?: string };
+			if (body?.data && typeof body.data === 'string') {
+				const buffer = Buffer.from(body.data, 'base64');
+				await fs.writeFile(localFile, buffer);
+				return { success: true, message: `Downloaded backup ${id}`, filePath: localFile, sizeBytes: buffer.length };
+			}
+
+			await fs.writeFile(localFile, JSON.stringify(res.data));
+			return { success: true, message: `Downloaded backup ${id}`, filePath: localFile };
+		} catch (err) {
+			return { success: false, message: `Download failed: ${err}` };
+		}
+	}
+
+	async getProfiles(): Promise<unknown> {
+		const res = await this.request(`${this.baseUrl}/profiles`, 'GET');
+		return res.data;
+	}
+}

mcp/servers/mokobackup/src/types.ts

@@ -0,0 +1,58 @@
+export interface BackupTarget {
+	name: string;
+	type: 'mysql' | 'postgres' | 'files' | 'akeeba' | 'mokobackup' | 'dolibarr';
+	sshHost?: string;
+	sshPort?: number;
+	sshUser?: string;
+	sshKeyPath?: string;
+	database?: string;
+	dbUser?: string;
+	dbPassword?: string;
+	remotePaths?: string[];
+	localBackupDir: string;
+	/** Akeeba/MokoBackup: site base URL (e.g. https://clarksvillefurs.com) */
+	siteUrl?: string;
+	/** Akeeba/MokoBackup: Joomla API token (Bearer auth) */
+	secretWord?: string;
+	/** Akeeba/MokoBackup: backup profile ID (default 1) */
+	profileId?: number;
+	/** Dolibarr-specific: path to conf/conf.php on the remote server */
+	confPath?: string;
+}
+
+export interface BackupConfig {
+	targets: Record<string, BackupTarget>;
+	defaultTarget: string;
+}
+
+export interface BackupResult {
+	success: boolean;
+	message: string;
+	filePath?: string;
+	sizeBytes?: number;
+}
+
+export interface AkeebaBackupRecord {
+	id: string;
+	description: string;
+	status: string;
+	origin: string;
+	type: string;
+	profile_id: number;
+	archivename: string;
+	absolute_path: string;
+	multipart: number;
+	tag: string;
+	backupstart: string;
+	backupend: string;
+	filesexist: number;
+	remote_filename: string;
+	total_size: number;
+}
+
+export interface AkeebaApiResponse {
+	body: {
+		status: number;
+		data: unknown;
+	};
+}

mcp/servers/mokobackup/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "Node16",
+		"moduleResolution": "Node16",
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

mcp/servers/mokocrm_api/.mokogitea/CLAUDE.md

@@ -0,0 +1,44 @@
+# mcp_mokocrm
+
+MCP server for Dolibarr ERP/CRM REST API operations — third parties, invoices, proposals, projects, tasks, contacts, and business management.
+
+## Quick Reference
+
+| Field | Value |
+|---|---|
+| **Package** | `@mokoconsulting/mcp-mokocrm-api` |
+| **Entry** | `dist/index.js` |
+| **Config** | `~/.mcp_mokocrm.json` (override: `DOLIBARR_API_MCP_CONFIG` env var) |
+| **Language** | TypeScript |
+| **Branch** | develop on `dev`, merge to `main` (protected) |
+
+## Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript → dist/
+npm run dev          # Watch mode
+```
+
+## Architecture
+
+```
+src/
+├── index.ts         # MCP server entry, tool registration
+├── config.ts        # Loads ~/.mcp_mokocrm.json, resolves connections
+├── client.ts        # Dolibarr REST API client wrapper
+├── tools/           # Individual tool implementations
+└── types.ts         # DolibarrConfig, DolibarrConnection types
+```
+
+- Config defines **connections** — each is a Dolibarr instance with URL + API key
+- Default connections: production (crm.mokoconsulting.tech), dev (crm.dev.mokoconsulting.tech)
+- No demo environment for CRM
+
+## Rules
+
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
+- **Attribution**: `Authored-by: Moko Consulting`
+- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
+- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)

mcp/servers/mokocrm_api/CHANGELOG.md

@@ -0,0 +1,62 @@
+<!--	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: 0.0.0
+	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]
+
+## [0.0] - 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 |

mcp/servers/mokocrm_api/CONTRIBUTING.md

@@ -0,0 +1,161 @@
+<!--	Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+
+	This file is part of a Moko Consulting project.
+
+	SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
+
+	This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+
+	This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+	You should have received a copy of the GNU General Public License (./LICENSE).
+
+	# FILE INFORMATION
+	DEFGROUP: 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
+
+We appreciate your interest in contributing to this project! This document provides guidelines for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [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
+
+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.
+
+## Getting Started
+
+1. Fork the repository
+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
+
+### Reporting Bugs
+
+- Use the Gitea issue tracker
+- 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
+
+If you want to add support for a Dolibarr API endpoint not yet covered:
+
+1. Check the [Dolibarr API Explorer](https://your-dolibarr.com/api/index.php/explorer) for endpoint details
+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
+
+- Pick an issue or create one
+- Fork the repository and create a branch
+- Make your changes following the project conventions
+- Submit a pull request
+
+## Development Workflow
+
+1. Ensure your fork is up to date with the main repository
+2. Create a feature branch from `main`
+3. Make your changes
+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
+6. Commit your changes with clear messages
+7. Push to your fork
+8. Create a pull request
+
+## Commit Messages
+
+Follow the conventional commit format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`, `revert`
+
+Example:
+```
+feat(tools): add shipment management tools
+
+Add dolibarr_shipments_list, dolibarr_shipment_get, and
+dolibarr_shipment_validate tools for the /shipments API endpoint.
+```
+
+## Pull Request Process
+
+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
+
+- 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 |

mcp/servers/mokocrm_api/README.md

@@ -0,0 +1,370 @@
+# dolibarr-api-mcp
+
+MCP server for Dolibarr ERP/CRM REST API operations
+
+![Language](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen?style=flat-square&logo=node.js&logoColor=white) ![MCP](https://img.shields.io/badge/MCP-1.12+-blue?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-dolibarr--api--mcp-blue?style=flat-square)
+
+| Field | Value |
+|---|---|
+| **Language** | TypeScript |
+| **License** | GPL-3.0-or-later |
+| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp) |
+| **Node.js** | >= 20.0.0 |
+| **MCP SDK** | @modelcontextprotocol/sdk ^1.12.1 |
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that bridges AI assistants (Claude Code, Cursor, etc.) with Dolibarr's built-in REST API. Manage invoices, proposals, orders, products, third parties, projects, and more -- directly from your AI assistant.
+
+---
+
+## Quick Start
+
+```sh
+git clone https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp.git
+cd dolibarr-api-mcp
+npm install
+npm run build
+npm run setup
+```
+
+The interactive setup wizard will prompt for your Dolibarr instance URL, API key, and TLS settings.
+
+Register with Claude Code (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "dolibarr-api": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/dolibarr-api-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Verify with: `dolibarr_status` -- returns the Dolibarr version and server info.
+
+---
+
+## Tools (85)
+
+Every tool accepts an optional `connection` parameter to target a specific named Dolibarr instance (defaults to the configured default).
+
+### Third Parties (5)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_thirdparties_list` | List/search third parties with pagination and SQL filters |
+| `dolibarr_thirdparty_get` | Get a third party by ID |
+| `dolibarr_thirdparty_create` | Create a new third party (customer, supplier, or prospect) |
+| `dolibarr_thirdparty_update` | Update an existing third party |
+| `dolibarr_thirdparty_delete` | Delete a third party |
+
+### Contacts (5)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_contacts_list` | List/search contacts with pagination |
+| `dolibarr_contact_get` | Get a contact by ID |
+| `dolibarr_contact_create` | Create a new contact linked to a third party |
+| `dolibarr_contact_update` | Update an existing contact |
+| `dolibarr_contact_delete` | Delete a contact |
+
+### Invoices (7)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_invoices_list` | List/search invoices with status and date filters |
+| `dolibarr_invoice_get` | Get an invoice by ID |
+| `dolibarr_invoice_create` | Create a new invoice for a third party |
+| `dolibarr_invoice_add_line` | Add a line item to an invoice |
+| `dolibarr_invoice_validate` | Validate a draft invoice |
+| `dolibarr_invoice_set_paid` | Mark an invoice as paid |
+| `dolibarr_invoice_add_payment` | Record a payment against an invoice |
+| `dolibarr_invoice_payments` | List payments for an invoice |
+
+### Proposals / Quotes (7)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_proposals_list` | List/search proposals with pagination |
+| `dolibarr_proposal_get` | Get a proposal by ID |
+| `dolibarr_proposal_create` | Create a new proposal for a third party |
+| `dolibarr_proposal_add_line` | Add a line item to a proposal |
+| `dolibarr_proposal_validate` | Validate a draft proposal |
+| `dolibarr_proposal_close` | Close a proposal (signed or refused) |
+
+### Orders (5)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_orders_list` | List/search orders with pagination |
+| `dolibarr_order_get` | Get an order by ID |
+| `dolibarr_order_create` | Create a new order for a third party |
+| `dolibarr_order_add_line` | Add a line item to an order |
+| `dolibarr_order_validate` | Validate a draft order |
+
+### Products & Services (5)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_products_list` | List/search products and services |
+| `dolibarr_product_get` | Get a product by ID |
+| `dolibarr_product_create` | Create a new product or service |
+| `dolibarr_product_update` | Update an existing product |
+| `dolibarr_product_stock` | Get stock levels for a product |
+
+### Projects (4)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_projects_list` | List/search projects |
+| `dolibarr_project_get` | Get a project by ID |
+| `dolibarr_project_create` | Create a new project |
+| `dolibarr_project_update` | Update an existing project |
+
+### Tasks (6)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_tasks_list` | List tasks (optionally filtered by project) |
+| `dolibarr_task_get` | Get a task by ID |
+| `dolibarr_task_create` | Create a new task within a project |
+| `dolibarr_task_update` | Update an existing task |
+| `dolibarr_task_timespent_list` | List time entries for a task |
+| `dolibarr_task_timespent_add` | Add a time entry to a task |
+
+### Contracts (4)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_contracts_list` | List/search contracts |
+| `dolibarr_contract_get` | Get a contract by ID |
+| `dolibarr_contract_create` | Create a new contract |
+| `dolibarr_contract_validate` | Validate a draft contract |
+
+### Shipments (5)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_shipments_list` | List/search shipments |
+| `dolibarr_shipment_get` | Get a shipment by ID |
+| `dolibarr_shipment_create` | Create a new shipment from an order |
+| `dolibarr_shipment_validate` | Validate a draft shipment |
+| `dolibarr_shipment_close` | Close a shipment |
+
+### Agenda Events (4)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_agendaevents_list` | List/search agenda events |
+| `dolibarr_agendaevent_get` | Get an agenda event by ID |
+| `dolibarr_agendaevent_create` | Create a new agenda event |
+| `dolibarr_agendaevent_update` | Update an existing agenda event |
+
+### Tickets (3)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_tickets_list` | List/search tickets |
+| `dolibarr_ticket_get` | Get a ticket by ID |
+| `dolibarr_ticket_create` | Create a new support ticket |
+
+### Members (2)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_members_list` | List/search members (foundation/association module) |
+| `dolibarr_member_get` | Get a member by ID |
+
+### Users (3)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_users_list` | List Dolibarr users |
+| `dolibarr_user_get` | Get a user by ID |
+| `dolibarr_user_create` | Create a new Dolibarr user |
+
+### Expense Reports (3)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_expensereports_list` | List/search expense reports |
+| `dolibarr_expensereport_get` | Get an expense report by ID |
+| `dolibarr_expensereport_create` | Create a new expense report |
+
+### Interventions (2)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_interventions_list` | List/search interventions |
+| `dolibarr_intervention_get` | Get an intervention by ID |
+
+### Documents (3)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_documents_list` | List documents attached to a module element |
+| `dolibarr_document_download` | Download a document file |
+| `dolibarr_document_builddoc` | Generate a PDF document for an element |
+
+### Stock & Warehouses (3)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_warehouses_list` | List warehouses |
+| `dolibarr_stockmovements_list` | List stock movements |
+| `dolibarr_stockmovement_create` | Create a stock movement |
+
+### Bank Accounts (2)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_bankaccounts_list` | List bank accounts |
+| `dolibarr_bankaccount_lines` | List transaction lines for a bank account |
+
+### Categories (3)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_categories_list` | List categories by type |
+| `dolibarr_category_get` | Get a category by ID |
+| `dolibarr_category_create` | Create a new category |
+
+### Supplier Invoices & Orders (2)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_supplier_invoices_list` | List supplier (vendor) invoices |
+| `dolibarr_supplier_orders_list` | List supplier (vendor) orders |
+
+### Setup & System (5)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_status` | Check Dolibarr instance status and version |
+| `dolibarr_setup_company` | Get company/organization setup info |
+| `dolibarr_setup_modules` | List enabled Dolibarr modules |
+| `dolibarr_setup_dictionary` | Query Dolibarr dictionary tables (countries, currencies, etc.) |
+| `dolibarr_list_connections` | List all configured Dolibarr connections |
+
+### Generic (1)
+
+| Tool | Description |
+|---|---|
+| `dolibarr_api_request` | Make a raw API request to any Dolibarr endpoint |
+
+---
+
+## Configuration
+
+The config file is stored at `~/.dolibarr-api-mcp.json` (or set `DOLIBARR_API_MCP_CONFIG` for a custom path):
+
+```json
+{
+  "defaultConnection": "production",
+  "connections": {
+    "production": {
+      "baseUrl": "https://erp.example.com",
+      "apiKey": "your-api-key"
+    },
+    "staging": {
+      "baseUrl": "https://erp-staging.example.com",
+      "apiKey": "your-staging-key",
+      "insecure": true
+    }
+  }
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `defaultConnection` | Yes | Name of the default connection |
+| `connections` | Yes | Map of named connections |
+| `baseUrl` | Yes | Dolibarr instance URL (no trailing slash) |
+| `apiKey` | Yes | Dolibarr API key (`DOLAPIKEY` header auth) |
+| `insecure` | No | Set `true` to skip TLS verification (self-signed certs) |
+
+---
+
+## Architecture
+
+```
+AI Assistant  <-->  MCP (stdio)  <-->  DolibarrClient  <-->  Dolibarr REST API
+                                                              /api/index.php
+```
+
+- **Transport**: stdio (standard input/output)
+- **Auth**: `DOLAPIKEY` HTTP header (Dolibarr's native per-user API key)
+- **HTTP**: Uses `node:https`/`node:http` (not `fetch`) for reliable self-signed TLS support on Node.js 24+
+- **Validation**: Zod schemas for all tool inputs
+- **Filtering**: `buildSqlFilter()` helper for Dolibarr's `sqlfilters` parameter with injection-safe escaping
+
+### Source Layout
+
+| File | Purpose |
+|---|---|
+| `src/index.ts` | Server entry point -- registers all MCP tools with Zod schemas |
+| `src/client.ts` | `DolibarrClient` HTTP class (GET/POST/PUT/DELETE) |
+| `src/config.ts` | Configuration loader for multi-instance connections |
+| `src/types.ts` | TypeScript interfaces (`DolibarrConnection`, `DolibarrConfig`, `ApiResponse`) |
+| `scripts/setup.mjs` | Interactive setup wizard for creating the config file |
+| `config.example.json` | Example configuration with multiple connections |
+
+---
+
+## Examples
+
+**List all customers:**
+```
+dolibarr_thirdparties_list with search="acme", limit=10
+```
+
+**Create an invoice and add a line:**
+```
+dolibarr_invoice_create with socid=42
+dolibarr_invoice_add_line with id=<invoice_id>, desc="Consulting services", subprice=150.00, qty=8
+dolibarr_invoice_validate with id=<invoice_id>
+```
+
+**Check a specific Dolibarr instance:**
+```
+dolibarr_status with connection="staging"
+```
+
+**Raw API request for unsupported endpoints:**
+```
+dolibarr_api_request with method="GET", endpoint="/categories", params={"type": "product"}
+```
+
+---
+
+## Guides
+
+| Page | Description |
+|---|---|
+| [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/wiki/INSTALLATION) | Prerequisites, install steps, Claude Code registration, troubleshooting |
+
+## Reference
+
+| Page | Description |
+|---|---|
+| [ARCHITECTURE](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/wiki/ARCHITECTURE) | Component overview, design decisions, data flow, API module coverage |
+
+---
+
+## Documentation
+
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/wiki).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and contribution instructions.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.
+
+---
+
+*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

mcp/servers/mokocrm_api/SECURITY.md

@@ -0,0 +1,114 @@
+<!--
+Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+
+This file is part of a Moko Consulting project.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+# FILE INFORMATION
+DEFGROUP: dolibarr-api-mcp.Documentation
+INGROUP: dolibarr-api-mcp
+REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
+PATH: /SECURITY.md
+VERSION: 01.00.00
+BRIEF: Security vulnerability reporting and handling policy
+-->
+
+# Security Policy
+
+## Purpose and Scope
+
+This document defines the security vulnerability reporting, response, and disclosure policy for dolibarr-api-mcp and all repositories governed by MokoStandards.
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+Only the current major version receives security updates.
+
+## Reporting a Vulnerability
+
+Report security vulnerabilities via Gitea issue (preferred):
+https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/issues/new?template=security.yaml
+
+Or email: hello@mokoconsulting.tech
+
+### Where to Report
+
+**DO NOT** create public issues for security vulnerabilities.
+
+Report security vulnerabilities privately to:
+
+**Email**: `hello@mokoconsulting.tech`
+
+**Subject Line**: `[SECURITY] Brief Description`
+
+### What to Include
+
+1. **Description**: Clear explanation of the vulnerability
+2. **Impact**: Potential security impact and severity assessment
+3. **Affected Versions**: Which versions are vulnerable
+4. **Reproduction Steps**: Detailed steps to reproduce the issue
+5. **Proof of Concept**: Code or demonstration (if applicable)
+6. **Suggested Fix**: Proposed remediation (if known)
+
+### Response Timeline
+
+* **Initial Response**: Within 3 business days
+* **Assessment Complete**: Within 7 business days
+* **Fix Timeline**: Depends on severity (see below)
+
+## Severity Classification
+
+### Critical
+* API key exposure or leakage
+* Remote code execution via API parameters
+* Authentication bypass
+* **Fix Timeline**: 7 days
+
+### High
+* SQL injection via sqlfilters parameter
+* Unauthorized access to Dolibarr data
+* **Fix Timeline**: 14 days
+
+### Medium
+* Information disclosure (limited scope)
+* Configuration file exposure
+* **Fix Timeline**: 30 days
+
+### Low
+* Security best practice violations
+* Minor information leaks
+* **Fix Timeline**: 60 days or next release
+
+## Security Considerations
+
+### API Key Storage
+
+- API keys are stored in `~/.dolibarr-api-mcp.json` with user-only file permissions
+- Never commit API keys to version control
+- The `.gitignore` excludes `.mcp.json` and environment files
+
+### SQL Filter Safety
+
+- The `buildSqlFilter()` helper escapes single quotes to prevent SQL injection via the `sqlfilters` parameter
+- All user-provided search terms are wrapped with the helper before being sent to Dolibarr
+
+### TLS Verification
+
+- The `insecure` connection option disables TLS certificate verification
+- This should only be used for local development with self-signed certificates
+- Production connections should always use valid TLS certificates
+
+## Attribution and Recognition
+
+We acknowledge and appreciate responsible disclosure. With your permission, we will credit you in security advisories and release notes.
+
+## Revision History
+
+| Date | Version | Author | Notes |
+| --- | --- | --- | --- |
+| 2026-05-07 | 0.0.1 | jmiller | Initial security policy |

mcp/servers/mokocrm_api/config.example.json

@@ -0,0 +1,18 @@
+{
+	"defaultConnection": "production",
+	"connections": {
+		"local-dev": {
+			"baseUrl": "https://localhost:8080",
+			"apiKey": "your-dolibarr-api-key-here",
+			"insecure": true
+		},
+		"production": {
+			"baseUrl": "https://erp.example.com",
+			"apiKey": "your-production-api-key"
+		},
+		"staging": {
+			"baseUrl": "https://erp-staging.example.com",
+			"apiKey": "your-staging-api-key"
+		}
+	}
+}

mcp/servers/mokocrm_api/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@mokoconsulting/mcp-mokocrm-api",
+	"version": "1.0.0",
+	"description": "MCP server for Dolibarr ERP/CRM REST API operations",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": {
+		"dolibarr-api-mcp": "dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"start": "node dist/index.js",
+		"lint": "eslint src/",
+		"setup": "node scripts/setup.mjs",
+		"clean": "rm -rf dist/"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.1",
+		"zod": "^3.24.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.3",
+		"typescript": "^5.8.3"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"license": "GPL-3.0-or-later",
+	"author": "Moko Consulting <hello@mokoconsulting.tech>",
+	"repository": {
+		"type": "git",
+		"url": "https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp.git"
+	}
+}

mcp/servers/mokocrm_api/scripts/setup.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: dolibarr-api-mcp.Scripts
+ * INGROUP: dolibarr-api-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
+ * PATH: /scripts/setup.mjs
+ * VERSION: 01.00.00
+ * BRIEF: Interactive setup — prompts for Dolibarr API connection details and writes config
+ */
+
+import { createInterface } from 'node:readline/promises';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+const CONFIG_PATH = resolve(homedir(), '.dolibarr-api-mcp.json');
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+async function prompt(question, defaultValue) {
+	const suffix = defaultValue ? ` [${defaultValue}]` : '';
+	const answer = await rl.question(`${question}${suffix}: `);
+	return answer.trim() || defaultValue || '';
+}
+
+async function promptRequired(question) {
+	let answer = '';
+	while (!answer) {
+		answer = (await rl.question(`${question}: `)).trim();
+		if (!answer) {
+			console.log('  This field is required.');
+		}
+	}
+	return answer;
+}
+
+async function main() {
+	console.log('');
+	console.log('=== dolibarr-api-mcp Setup ===');
+	console.log('');
+	console.log('This will create your configuration file at:');
+	console.log(`  ${CONFIG_PATH}`);
+	console.log('');
+
+	// Check for existing config
+	let existing = null;
+	try {
+		const raw = await readFile(CONFIG_PATH, 'utf-8');
+		existing = JSON.parse(raw);
+		console.log('Existing config found. You can add a new connection or overwrite.');
+		console.log(`  Current connections: ${Object.keys(existing.connections).join(', ')}`);
+		console.log('');
+	} catch {
+		// No existing config
+	}
+
+	const connectionName = await prompt('Connection name', 'production');
+	const baseUrl = await promptRequired('Dolibarr URL (e.g. https://erp.example.com)');
+	const apiKey = await promptRequired('Dolibarr API key (from user settings or Setup > Security)');
+
+	const cleanUrl = baseUrl.replace(/\/+$/, '');
+
+	const insecureAnswer = await prompt('Skip TLS verification for self-signed certs? (y/N)', 'N');
+	const insecure = insecureAnswer.toLowerCase() === 'y';
+
+	const connection = { baseUrl: cleanUrl, apiKey };
+	if (insecure) {
+		connection.insecure = true;
+	}
+
+	let config;
+	if (existing) {
+		config = existing;
+		config.connections[connectionName] = connection;
+		const setDefault = await prompt(`Set "${connectionName}" as default connection? (y/N)`, 'N');
+		if (setDefault.toLowerCase() === 'y') {
+			config.defaultConnection = connectionName;
+		}
+	} else {
+		config = {
+			defaultConnection: connectionName,
+			connections: {
+				[connectionName]: connection,
+			},
+		};
+	}
+
+	await writeFile(CONFIG_PATH, JSON.stringify(config, null, '\t') + '\n', 'utf-8');
+
+	console.log('');
+	console.log(`Config written to ${CONFIG_PATH}`);
+	console.log(`  Connection "${connectionName}" configured for ${cleanUrl}`);
+	console.log('');
+
+	const addAnother = await prompt('Add another connection? (y/N)', 'N');
+	if (addAnother.toLowerCase() === 'y') {
+		rl.close();
+		// Re-run to add another
+		const { execFileSync } = await import('node:child_process');
+		execFileSync('node', [new URL(import.meta.url).pathname], { stdio: 'inherit' });
+		return;
+	}
+
+	console.log('Setup complete. You can now use the MCP server.');
+	console.log('');
+	rl.close();
+}
+
+main().catch((err) => {
+	console.error(`Setup failed: ${err.message}`);
+	rl.close();
+	process.exit(1);
+});

mcp/servers/mokocrm_api/src/client.ts

@@ -0,0 +1,122 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: dolibarr-api-mcp.Client
+ * INGROUP: dolibarr-api-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
+ * PATH: /src/client.ts
+ * VERSION: 01.00.00
+ * BRIEF: HTTP client for Dolibarr REST API
+ */
+
+import * as https from 'node:https';
+import * as http from 'node:http';
+import type { DolibarrConnection, ApiResponse } from './types.js';
+
+const API_PREFIX = '/api/index.php';
+const TIMEOUT_MS = 30_000;
+
+export class DolibarrClient {
+	private readonly base_url: string;
+	private readonly headers: Record<string, string>;
+	private readonly insecure: boolean;
+
+	constructor(conn: DolibarrConnection) {
+		this.base_url = conn.baseUrl.replace(/\/+$/, '') + API_PREFIX;
+		this.headers = {
+			'DOLAPIKEY': conn.apiKey,
+			'Content-Type': 'application/json',
+			'Accept': 'application/json',
+		};
+		this.insecure = conn.insecure ?? false;
+	}
+
+	async get(endpoint: string, params?: Record<string, string>): Promise<ApiResponse> {
+		const url = this.buildUrl(endpoint, params);
+		return this.request(url, 'GET');
+	}
+
+	async post(endpoint: string, body?: unknown): Promise<ApiResponse> {
+		const url = this.buildUrl(endpoint);
+		return this.request(url, 'POST', body);
+	}
+
+	async put(endpoint: string, body: unknown): Promise<ApiResponse> {
+		const url = this.buildUrl(endpoint);
+		return this.request(url, 'PUT', body);
+	}
+
+	async delete(endpoint: string): Promise<ApiResponse> {
+		const url = this.buildUrl(endpoint);
+		return this.request(url, 'DELETE');
+	}
+
+	private buildUrl(endpoint: string, params?: Record<string, string>): string {
+		const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+		const url = new URL(`${this.base_url}${path}`);
+		if (params) {
+			for (const [key, value] of Object.entries(params)) {
+				url.searchParams.set(key, value);
+			}
+		}
+		return url.toString();
+	}
+
+	private request(url: string, method: string, body?: unknown): Promise<ApiResponse> {
+		return new Promise((resolve, reject) => {
+			const parsed = new URL(url);
+			const is_https = parsed.protocol === 'https:';
+			const transport = is_https ? https : http;
+
+			const options: https.RequestOptions = {
+				hostname: parsed.hostname,
+				port: parsed.port || (is_https ? 443 : 80),
+				path: parsed.pathname + parsed.search,
+				method,
+				headers: { ...this.headers },
+				timeout: TIMEOUT_MS,
+			};
+
+			if (this.insecure && is_https) {
+				options.rejectUnauthorized = false;
+			}
+
+			const payload = body !== undefined ? JSON.stringify(body) : undefined;
+			if (payload) {
+				(options.headers as Record<string, string>)['Content-Length'] = Buffer.byteLength(payload).toString();
+			}
+
+			const req = transport.request(options, (res) => {
+				const chunks: Buffer[] = [];
+				res.on('data', (chunk: Buffer) => chunks.push(chunk));
+				res.on('end', () => {
+					const raw = Buffer.concat(chunks).toString('utf-8');
+					let data: unknown;
+
+					try {
+						data = JSON.parse(raw);
+					} catch {
+						data = raw;
+					}
+
+					resolve({ status: res.statusCode ?? 0, data });
+				});
+			});
+
+			req.on('error', (err) => reject(err));
+			req.on('timeout', () => {
+				req.destroy();
+				reject(new Error('Request timed out'));
+			});
+
+			if (payload) {
+				req.write(payload);
+			}
+			req.end();
+		});
+	}
+}

mcp/servers/mokocrm_api/src/config.ts

@@ -0,0 +1,58 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: dolibarr-api-mcp.Config
+ * INGROUP: dolibarr-api-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
+ * PATH: /src/config.ts
+ * VERSION: 01.00.00
+ * BRIEF: Configuration loader for Dolibarr API MCP connections
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { DolibarrConfig, DolibarrConnection } from './types.js';
+
+const CONFIG_FILENAME = '.mcp_mokocrm.json';
+
+export async function loadConfig(): Promise<DolibarrConfig> {
+	const config_path = process.env.DOLIBARR_API_MCP_CONFIG
+		? resolve(process.env.DOLIBARR_API_MCP_CONFIG)
+		: resolve(homedir(), CONFIG_FILENAME);
+
+	try {
+		const raw = await readFile(config_path, 'utf-8');
+		const parsed = JSON.parse(raw) as Partial<DolibarrConfig>;
+
+		if (!parsed.connections || Object.keys(parsed.connections).length === 0) {
+			throw new Error('No connections defined in config');
+		}
+
+		return {
+			connections: parsed.connections,
+			defaultConnection: parsed.defaultConnection ?? Object.keys(parsed.connections)[0],
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(
+			`Failed to load config from ${config_path}: ${message}\n` +
+			`Create ${config_path} — see config.example.json for format.`,
+		);
+	}
+}
+
+export function getConnection(config: DolibarrConfig, name?: string): DolibarrConnection {
+	const key = name ?? config.defaultConnection;
+	const conn = config.connections[key];
+	if (!conn) {
+		throw new Error(
+			`Connection "${key}" not found. Available: ${Object.keys(config.connections).join(', ')}`,
+		);
+	}
+	return conn;
+}

mcp/servers/mokocrm_api/src/types.ts

@@ -0,0 +1,31 @@
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ *
+ * This file is part of a Moko Consulting project.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * FILE INFORMATION
+ * DEFGROUP: dolibarr-api-mcp.Types
+ * INGROUP: dolibarr-api-mcp
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
+ * PATH: /src/types.ts
+ * VERSION: 01.00.00
+ * BRIEF: TypeScript type definitions for Dolibarr API MCP server
+ */
+
+export interface DolibarrConnection {
+	baseUrl: string;
+	apiKey: string;
+	/** Skip TLS certificate verification (self-signed certs) */
+	insecure?: boolean;
+}
+
+export interface DolibarrConfig {
+	connections: Record<string, DolibarrConnection>;
+	defaultConnection: string;
+}
+
+export interface ApiResponse {
+	status: number;
+	data: unknown;
+}

mcp/servers/mokocrm_api/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "Node16",
+		"moduleResolution": "Node16",
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

mcp/servers/mokodreamhost/.mokogitea/CLAUDE.md

@@ -0,0 +1,42 @@
+# mcp_mokodreamhost
+
+MCP server for DreamHost API — DNS records, hosting, and domain management.
+
+## Quick Reference
+
+| Field | Value |
+|---|---|
+| **Package** | `@mokoconsulting/dreamhost-mcp` |
+| **Entry** | `dist/index.js` |
+| **Config** | `~/.mcp_mokodreamhost.json` (override: `DREAMHOST_MCP_CONFIG` env var) |
+| **Language** | TypeScript |
+| **Branch** | develop on `dev`, merge to `main` (protected) |
+
+## Commands
+
+```bash
+npm install          # Install dependencies
+npm run build        # Compile TypeScript → dist/
+npm run dev          # Watch mode
+```
+
+## Architecture
+
+```
+src/
+├── index.ts         # MCP server entry, tool registration
+├── config.ts        # Loads ~/.mcp_mokodreamhost.json (just apiKey)
+├── client.ts        # DreamHost API client wrapper
+└── types.ts         # DreamHostConfig type
+```
+
+- Simple config — just an API key
+- Manages DNS records, domains, and hosting for all DreamHost-hosted sites
+
+## Rules
+
+- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
+- **Attribution**: `Authored-by: Moko Consulting`
+- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
+- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
+- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)

mcp/servers/mokodreamhost/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [1.0] — 2026-05-08
+
+### Added
+- Initial release

mcp/servers/mokodreamhost/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+See [standards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki).

mcp/servers/mokodreamhost/README.md

@@ -0,0 +1,159 @@
+# dreamhost-mcp
+
+[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](LICENSE)
+[![Node: >=20](https://img.shields.io/badge/Node-%3E%3D20-green.svg)](https://nodejs.org)
+[![MCP SDK](https://img.shields.io/badge/MCP_SDK-%5E1.12.1-purple.svg)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org)
+
+MCP server for the [DreamHost API](https://help.dreamhost.com/hc/en-us/articles/217560167-API-overview) -- DNS records, domains, hosting accounts, MySQL databases, and email management.
+
+Part of [Moko Consulting](https://mokoconsulting.tech) infrastructure.
+
+---
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `dreamhost_dns_list` | List all DNS records (optionally filter by domain) |
+| `dreamhost_dns_add` | Add a DNS record (A, AAAA, CNAME, MX, TXT, SRV) |
+| `dreamhost_dns_remove` | Remove a DNS record (must match record, type, and value exactly) |
+| `dreamhost_dns_check` | Check if a DNS record exists for a domain (optional type filter) |
+| `dreamhost_domain_list` | List all hosted domains |
+| `dreamhost_domain_registrations` | List domain registrations with expiry dates |
+| `dreamhost_user_list` | List hosting users and accounts |
+| `dreamhost_account_status` | Get account status and usage |
+| `dreamhost_api_commands` | List available API commands for the configured key |
+| `dreamhost_mysql_list` | List MySQL databases |
+| `dreamhost_mysql_users` | List MySQL database users |
+| `dreamhost_mail_list` | List email addresses (optionally filter by domain) |
+| `dreamhost_rewards_referrals` | List referral rewards |
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 20
+- A **DreamHost API key** -- generate one at [DreamHost Panel > Web Panel API](https://panel.dreamhost.com/?tree=home.api)
+
+---
+
+## Installation
+
+```bash
+git clone https://git.mokoconsulting.tech/MokoConsulting/dreamhost-mcp.git
+cd dreamhost-mcp
+npm install && npm run build
+```
+
+---
+
+## Configuration
+
+Create `~/.dreamhost-mcp.json`:
+
+```json
+{
+  "apiKey": "your-dreamhost-api-key"
+}
+```
+
+Override the config path with the `DREAMHOST_MCP_CONFIG` environment variable:
+
+```bash
+DREAMHOST_MCP_CONFIG=/path/to/config.json node dist/index.js
+```
+
+### Claude Code (`.mcp.json`)
+
+Add to your project or global `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "dreamhost": {
+      "command": "node",
+      "args": ["/path/to/dreamhost-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## Usage Examples
+
+Once connected via MCP, the tools are available to the AI agent directly.
+
+**List all DNS records for a domain:**
+
+```
+dreamhost_dns_list(domain: "example.com")
+```
+
+**Add an A record:**
+
+```
+dreamhost_dns_add(record: "sub.example.com", type: "A", value: "1.2.3.4", comment: "staging server")
+```
+
+**Remove a DNS record:**
+
+```
+dreamhost_dns_remove(record: "sub.example.com", type: "A", value: "1.2.3.4")
+```
+
+**Check if a CNAME exists:**
+
+```
+dreamhost_dns_check(domain: "sub.example.com", type: "CNAME")
+```
+
+**List domain registrations and expiry dates:**
+
+```
+dreamhost_domain_registrations()
+```
+
+**List MySQL databases:**
+
+```
+dreamhost_mysql_list()
+```
+
+---
+
+## Project Structure
+
+```
+src/
+  index.ts      # MCP server entry point and tool definitions
+  client.ts     # DreamHost API HTTP client (HTTPS, 30s timeout)
+  config.ts     # Config file loader (~/.dreamhost-mcp.json)
+  types.ts      # TypeScript interfaces (DreamHostConfig, DnsRecord, ApiResponse)
+```
+
+---
+
+## Development
+
+```bash
+npm run dev      # watch mode (tsc --watch)
+npm run build    # compile TypeScript to dist/
+npm run start    # run the compiled server
+npm run clean    # remove dist/
+```
+
+---
+
+## Documentation
+
+Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/dreamhost-mcp/wiki).
+
+## License
+
+[GPL-3.0-or-later](LICENSE) -- Copyright (C) 2026 Moko Consulting
+
+---
+
+*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

mcp/servers/mokodreamhost/SECURITY.md

@@ -0,0 +1,3 @@
+# Security
+
+Report to hello@mokoconsulting.tech.

mcp/servers/mokodreamhost/config.example.json

@@ -0,0 +1,3 @@
+{
+	"apiKey": "your-dreamhost-api-key"
+}

mcp/servers/mokodreamhost/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@mokoconsulting/dreamhost-mcp",
+	"version": "1.0.0",
+	"description": "MCP server for DreamHost API — DNS records, hosting, and domain management",
+	"type": "module",
+	"main": "dist/index.js",
+	"bin": { "dreamhost-mcp": "dist/index.js" },
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --watch",
+		"start": "node dist/index.js",
+		"clean": "rm -rf dist/"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.1",
+		"zod": "^3.24.4"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.3",
+		"typescript": "^5.8.3"
+	},
+	"engines": { "node": ">=20.0.0" },
+	"license": "GPL-3.0-or-later",
+	"author": "Moko Consulting <hello@mokoconsulting.tech>"
+}

mcp/servers/mokodreamhost/src/client.ts

@@ -0,0 +1,84 @@
+import * as https from 'node:https';
+import { randomUUID } from 'node:crypto';
+import type { ApiResponse } from './types.js';
+
+const API_HOST = 'api.dreamhost.com';
+const TIMEOUT_MS = 30_000;
+
+export class DreamHostClient {
+	private readonly apiKey: string;
+
+	constructor(apiKey: string) {
+		this.apiKey = apiKey;
+	}
+
+	async callApi(cmd: string, params: Record<string, string> = {}): Promise<ApiResponse> {
+		const query = new URLSearchParams({
+			key: this.apiKey,
+			cmd,
+			format: 'json',
+			unique_id: randomUUID(),
+			...params,
+		});
+
+		return new Promise((resolve, reject) => {
+			const opts: https.RequestOptions = {
+				hostname: API_HOST,
+				port: 443,
+				path: `/?${query.toString()}`,
+				method: 'GET',
+				timeout: TIMEOUT_MS,
+			};
+
+			const req = https.request(opts, (res) => {
+				const chunks: Buffer[] = [];
+				res.on('data', (c: Buffer) => chunks.push(c));
+				res.on('end', () => {
+					const raw = Buffer.concat(chunks).toString();
+					try {
+						resolve(JSON.parse(raw) as ApiResponse);
+					} catch {
+						resolve({ result: 'error', reason: raw });
+					}
+				});
+			});
+			req.on('error', reject);
+			req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+			req.end();
+		});
+	}
+
+	async listDnsRecords(): Promise<ApiResponse> {
+		return this.callApi('dns-list_records');
+	}
+
+	async addDnsRecord(record: string, type: string, value: string, comment?: string): Promise<ApiResponse> {
+		const params: Record<string, string> = { record, type, value };
+		if (comment) params.comment = comment;
+		return this.callApi('dns-add_record', params);
+	}
+
+	async removeDnsRecord(record: string, type: string, value: string): Promise<ApiResponse> {
+		return this.callApi('dns-remove_record', { record, type, value });
+	}
+
+	async listDomains(): Promise<ApiResponse> {
+		return this.callApi('domain-list_domains');
+	}
+
+	async listRegistrations(): Promise<ApiResponse> {
+		return this.callApi('domain-list_registrations');
+	}
+
+	async listUsers(): Promise<ApiResponse> {
+		return this.callApi('account-list_accounts');
+	}
+
+	async accountStatus(): Promise<ApiResponse> {
+		return this.callApi('account-status');
+	}
+
+	async listCommands(): Promise<ApiResponse> {
+		return this.callApi('api-list_accessible_cmds');
+	}
+}

mcp/servers/mokodreamhost/src/config.ts

@@ -0,0 +1,19 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { DreamHostConfig } from './types.js';
+
+const CONFIG_FILENAME = '.mcp_mokodreamhost.json';
+
+export async function loadConfig(): Promise<DreamHostConfig> {
+	const configPath = process.env.DREAMHOST_MCP_CONFIG
+		? resolve(process.env.DREAMHOST_MCP_CONFIG)
+		: resolve(homedir(), CONFIG_FILENAME);
+
+	const raw = await readFile(configPath, 'utf-8');
+	const parsed = JSON.parse(raw) as Partial<DreamHostConfig>;
+	if (!parsed.apiKey) {
+		throw new Error(`No apiKey in ${configPath}`);
+	}
+	return { apiKey: parsed.apiKey };
+}