chore(version): pre-release bump to 01.00.01-rc [skip ci]

feat(ci): trigger RC build on PR draft to main, rename branch to rc
When a PR is opened or drafted targeting main, the pre-release workflow now automatically builds a release-candidate package and renames the source branch to 'rc'. Authored-by: Moko Consulting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-31 01:54:51 +00:00 · 2026-05-30 20:54:02 -05:00 · 2026-05-30 20:47:10 -05:00 · 2026-05-31 01:46:47 +00:00 · 2026-05-31 01:46:05 +00:00 · 2026-05-31 01:40:50 +00:00
86 changed files with 3941 additions and 1480 deletions
@@ -0,0 +1,62 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# PHP files
+*.php text eol=lf
+
+# XML manifests
+*.xml text eol=lf
+
+# Language files
+*.ini text eol=lf
+
+# SQL files
+*.sql text eol=lf
+
+# Shell scripts
+*.sh text eol=lf
+
+# Markdown
+*.md text eol=lf
+
+# YAML
+*.yml text eol=lf
+*.yaml text eol=lf
+
+# CSS/JS
+*.css text eol=lf
+*.js text eol=lf
+
+# JSON
+*.json text eol=lf
+
+# Windows scripts
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# Binary files
+*.zip binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.webp binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+
+# Export ignore (not included in archives)
+.mokogitea/ export-ignore
+.editorconfig export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.gitmessage export-ignore
+CLAUDE.md export-ignore
+CONTRIBUTING.md export-ignore
+CODE_OF_CONDUCT.md export-ignore
+Makefile export-ignore
+composer.json export-ignore
+phpstan.neon export-ignore
@@ -0,0 +1,204 @@
+# ============================================================
+# Local task tracking (not version controlled)
+# ============================================================
+TODO.md
+
+# ============================================================
+# Environment and secrets
+# ============================================================
+.env
+.env.local
+.env.*.local
+*.local.php
+*.secret.php
+configuration.php
+configuration.*.php
+configuration.local.php
+conf/conf.php
+conf/conf*.php
+secrets/
+*.secrets.*
+
+# ============================================================
+# Logs, dumps and databases
+# ============================================================
+*.db
+*.db-journal
+*.dump
+*.log
+*.pid
+*.seed
+
+
+# ============================================================
+# OS / Editor / IDE cruft
+# ============================================================
+.DS_Store
+Thumbs.db
+desktop.ini
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+$RECYCLE.BIN/
+System Volume Information/
+*.lnk
+Icon?
+.idea/
+.settings/
+.claude/
+.vscode/*
+!.vscode/tasks.json
+!.vscode/settings.json.example
+!.vscode/extensions.json
+*.code-workspace
+*.sublime*
+.project
+.buildpath
+.classpath
+*.bak
+*.swp
+*.swo
+*.tmp
+*.old
+*.orig
+
+# ============================================================
+# Dev scripts and scratch
+# ============================================================
+TODO.md
+todo*
+*ffs*
+
+# ============================================================
+# SFTP / sync tools
+# ============================================================
+sftp-config*.json
+sftp-config.json.template
+sftp-settings.json
+
+# ============================================================
+# Sublime SFTP / FTP sync
+# ============================================================
+*.sublime-project
+*.sublime-workspace
+*.sublime-settings
+.libsass.json
+*.ffs*
+
+# ============================================================
+# Replit / cloud IDE
+# ============================================================
+.replit
+replit.md
+
+# ============================================================
+# Archives / release artifacts
+# ============================================================
+*.7z
+*.rar
+*.tar
+*.tar.gz
+*.tgz
+*.zip
+artifacts/
+release/
+releases/
+
+# ============================================================
+# Build outputs and site generators
+# ============================================================
+.mkdocs-build/
+.cache/
+.parcel-cache/
+build/
+dist/
+out/
+site/
+*.map
+*.css.map
+*.js.map
+*.tsbuildinfo
+
+# ============================================================
+# CI / test artifacts
+# ============================================================
+.coverage
+.coverage.*
+coverage/
+coverage.xml
+htmlcov/
+junit.xml
+reports/
+test-results/
+tests/_output/
+.github/local/
+.github/workflows/*.log
+
+# ============================================================
+# Node / JavaScript
+# ============================================================
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+.yarn/
+.npmrc
+.eslintcache
+package-lock.json
+
+# ============================================================
+# PHP / Composer tooling
+# ============================================================
+vendor/
+!src/media/vendor/
+composer.lock
+*.phar
+codeception.phar
+.phpunit.result.cache
+.php_cs.cache
+.php-cs-fixer.cache
+.phpstan.cache
+.phplint-cache
+phpmd-cache/
+.psalm/
+.rector/
+
+# ============================================================
+# Python
+# ============================================================
+__pycache__/
+*.py[cod]
+*.pyc
+*$py.class
+*.so
+.Python
+.eggs/
+*.egg
+*.egg-info/
+.installed.cfg
+MANIFEST
+develop-eggs/
+downloads/
+eggs/
+parts/
+sdist/
+var/
+wheels/
+ENV/
+env/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+.tox/
+.nox/
+*.cover
+*.coverage
+hypothesis/
+
+profile.ps1
+.mcp.json
@@ -5,9 +5,11 @@
 -->
 <moko-platform xmlns="https://standards.mokoconsulting.tech/moko-platform/1.0" schema-version="1.0">
  <identity>
-    <name>MokoOpenGraph</name>
+    <name>MokoJoomOpenGraph</name>
+    <display-name>Package - MokoJoomOpenGraph</display-name>
    <org>MokoConsulting</org>
    <description>Open Graph, SEO meta tags, and social sharing image management for Joomla articles and menu items</description>
+    <version>01.00.01</version>
    <license spdx="GPL-3.0-or-later">GNU General Public License v3</license>
  </identity>
  <governance>
@@ -0,0 +1,66 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: Gitea.Workflow
+# INGROUP: moko-platform.Release
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /.mokogitea/workflows/auto-bump.yml
+# VERSION: 09.02.00
+# BRIEF: Auto patch-bump version on every push to dev (skips merge commits)
+
+name: "Universal: Auto Version Bump"
+
+on:
+  push:
+    branches:
+      - dev
+      - rc
+      - 'feature/**'
+      - 'patch/**'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  GITEA_URL: ${{ vars.GITEA_URL || 'https://git.mokoconsulting.tech' }}
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    name: Version Bump
+    runs-on: release
+    if: >-
+      !contains(github.event.head_commit.message, '[skip ci]') &&
+      !contains(github.event.head_commit.message, '[skip bump]') &&
+      !startsWith(github.event.head_commit.message, 'Merge pull request')
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 1
+
+      - name: Setup moko-platform tools
+        run: |
+          if ! command -v composer &> /dev/null; then
+            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer >/dev/null 2>&1
+          fi
+          if [ -d "/opt/moko-platform/cli" ]; then
+            echo "MOKO_CLI=/opt/moko-platform/cli" >> "$GITHUB_ENV"
+          else
+            git clone --depth 1 --branch main --quiet \
+              "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/MokoConsulting/moko-platform.git" \
+              /tmp/moko-platform-api
+            cd /tmp/moko-platform-api && composer install --no-dev --no-interaction --quiet
+            echo "MOKO_CLI=/tmp/moko-platform-api/cli" >> "$GITHUB_ENV"
+          fi
+
+      - name: Bump version
+        run: |
+          php ${MOKO_CLI}/version_auto_bump.php \
+            --path . --branch "${GITHUB_REF_NAME}" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
+            --repo-url "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
@@ -27,13 +27,19 @@ name: "Universal: Build & Release"

 on:
  pull_request:
-    types: [closed]
+    types: [opened, closed]
    branches:
      - main
-    paths:
-      - 'src/**'
-      - 'htdocs/**'
  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
@@ -45,29 +51,98 @@ permissions:
  contents: write

 jobs:
-  release:
-    name: Build & Release Pipeline
+  # ── PR Opened → Rename branch to RC and build RC release ─────────────────────
+  promote-rc:
+    name: Promote to RC
    runs-on: release
    if: >-
-      github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'
+      (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.GA_TOKEN }}
-          fetch-depth: 0
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 1

      - name: Setup moko-platform tools
        env:
-          MOKO_CLONE_TOKEN: ${{ secrets.GA_TOKEN }}
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GH_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-api
+          git clone --depth 1 --branch main --quiet \
+            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
+            /tmp/moko-platform-api
+          cd /tmp/moko-platform-api
+          composer install --no-dev --no-interaction --quiet
+
+      - name: Rename branch to rc
+        run: |
+          php /tmp/moko-platform-api/cli/branch_rename.php \
+            --from "${{ github.event.pull_request.head.ref || 'dev' }}" --to rc \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" \
+            --api-base "${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}" \
+            --pr "${{ github.event.pull_request.number }}"
+
+      - name: Checkout rc and configure git
+        run: |
+          git fetch origin rc
+          git checkout rc
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Publish RC release
+        run: |
+          php /tmp/moko-platform-api/cli/release_publish.php \
+            --path . --stability rc --bump minor --branch rc \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}"
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Promoted to Release Candidate" >> $GITHUB_STEP_SUMMARY
+          echo "Branch renamed to rc, minor bump, RC + lesser stream releases built, updates.xml synced" >> $GITHUB_STEP_SUMMARY
+
+  # ── Merged PR → Build & Release (or promote RC to stable) ────────────────────
+  release:
+    name: Build & Release Pipeline
+    runs-on: release
+    if: >-
+      github.event.pull_request.merged == true ||
+      (github.event_name == 'workflow_dispatch' && inputs.action != 'promote-rc')
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
+          fetch-depth: 0
+
+      - name: Configure git for bot pushes
+        run: |
+          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "gitea-actions[bot]"
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Setup moko-platform tools
+        env:
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
+          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
+          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GH_MIRROR_TOKEN }}"}}'
        run: |
          # Ensure PHP + Composer are available
          if ! command -v composer &> /dev/null; then
            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer >/dev/null 2>&1
          fi
+          # Always fetch latest CLI tools — never use stale cache from previous runs
+          rm -rf /tmp/moko-platform-api
          git clone --depth 1 --branch main --quiet \
            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/moko-platform.git" \
            /tmp/moko-platform-api
@@ -75,504 +150,58 @@ jobs:
          composer install --no-dev --no-interaction --quiet


-      # -- PLATFORM DETECTION ---------------------------------------------------
-      - name: Detect platform
-        id: platform
+      - name: "Publish stable release"
        run: |
-          # Read platform from manifest.xml <platform> element; fallback to generic
-          PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*//p' .mokogitea/manifest.xml 2>/dev/null | head -1 | tr -d '[:space:]')
-          [ -z "$PLATFORM" ] && PLATFORM="generic"
-          echo "platform=$PLATFORM" >> "$GITHUB_OUTPUT"
-          echo "Platform detected: ${PLATFORM}"
-          # For packages: prefer pkg_*.xml in src/; fallback to any manifest
-          MANIFEST=$(find ./src -maxdepth 1 -name "pkg_*.xml" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          [ -z "$MANIFEST" ] && MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" ! -path "*/packages/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          [ -z "$MANIFEST" ] && MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          MOD_FILE=$(find . -maxdepth 4 -name "mod*.class.php" ! -path "./.git/*" -exec grep -l 'extends DolibarrModules' {} \; 2>/dev/null | head -1)
-          echo "manifest=${MANIFEST}" >> "$GITHUB_OUTPUT"
-          echo "mod_file=${MOD_FILE}" >> "$GITHUB_OUTPUT"
-
-      # -- STEP 1: Read version -----------------------------------------------
-      - name: "Step 1: Read version from README.md"
-        id: version
-        run: |
-          VERSION=$(php /tmp/moko-platform-api/cli/version_read.php --path . 2>/dev/null)
-          if [ -z "$VERSION" ]; then
-            echo "No VERSION in README.md — skipping release"
-            echo "skip=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          # Derive major.minor for branch naming (patches update existing branch)
-          MINOR=$(echo "$VERSION" | awk -F. '{printf "%s.%s", $1, $2}')
-          PATCH=$(echo "$VERSION" | awk -F. '{print $3}')
-
-          MAJOR=$(echo "$VERSION" | awk -F. '{print $1}')
-          MINOR_NUM=$(echo "$VERSION" | awk -F. '{print $2}')
-
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "branch=version/${MAJOR}" >> "$GITHUB_OUTPUT"
-          echo "minor=$MINOR" >> "$GITHUB_OUTPUT"
-          echo "major=$MAJOR" >> "$GITHUB_OUTPUT"
-          echo "release_tag=stable" >> "$GITHUB_OUTPUT"
-          echo "stability=stable" >> "$GITHUB_OUTPUT"
-          echo "skip=false" >> "$GITHUB_OUTPUT"
-          if [ "$PATCH" = "00" ] || [ "$PATCH" = "01" ]; then
-            echo "is_minor=true" >> "$GITHUB_OUTPUT"
-            echo "Version: $VERSION (first release for this minor — full pipeline)"
-          else
-            echo "is_minor=false" >> "$GITHUB_OUTPUT"
-            echo "Version: $VERSION (patch — platform version + badges only)"
-          fi
-
-      # -- STEP 1b: Bump minor version (stable = minor bump, reset patch) ------
-      - name: "Step 1b: Bump minor version for stable release"
-        if: steps.version.outputs.skip != 'true'
-        id: bump
-        run: |
-          CLI="/tmp/moko-platform-api/cli"
-          CURRENT=$(php $CLI/version_read.php --path . 2>/dev/null)
-          [ -z "$CURRENT" ] && { echo "skip=true" >> "$GITHUB_OUTPUT"; exit 0; }
-
-          # Minor bump via CLI (updates README.md in-place)
-          BUMP_OUT=$(php $CLI/version_bump.php --path . --minor)
-          VERSION=$(php $CLI/version_read.php --path . 2>/dev/null)
-          TODAY=$(date +%Y-%m-%d)
-          echo "Stable bump: ${BUMP_OUT}"
-
-          # Set platform-specific version (Joomla XML, Dolibarr mod*.class.php)
-          php $CLI/version_set_platform.php --path . --version "$VERSION" --stability stable --branch main
-
-          # Promote [Unreleased] in CHANGELOG.md
-          php $CLI/changelog_promote.php --path . --version "$VERSION" --date "$TODAY" 2>/dev/null || true
-
-          # Commit and push
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-          git remote set-url origin "https://jmiller:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
-          git add -A
-          git diff --cached --quiet || {
-            git commit -m "chore(version): bump ${CURRENT} → ${VERSION} [skip ci]"
-            git push origin HEAD:main 2>&1
-          }
-
-          # Override version output for rest of pipeline
-          MAJOR=$(echo "$VERSION" | cut -d. -f1)
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "major=${MAJOR}" >> "$GITHUB_OUTPUT"
-
-      - name: Check if already released
-        if: steps.version.outputs.skip != 'true'
-        id: check
-        run: |
-          TAG="${{ steps.version.outputs.release_tag }}"
-          BRANCH="${{ steps.version.outputs.branch }}"
-
-          TAG_EXISTS=false
-          BRANCH_EXISTS=false
-
-          git rev-parse "$TAG" >/dev/null 2>&1 && TAG_EXISTS=true
-          git ls-remote --heads origin "$BRANCH" 2>/dev/null | grep -q "$BRANCH" && BRANCH_EXISTS=true
-
-          echo "tag_exists=$TAG_EXISTS" >> "$GITHUB_OUTPUT"
-          echo "branch_exists=$BRANCH_EXISTS" >> "$GITHUB_OUTPUT"
-
-          # Tag and branch may persist across patch releases — never skip
-          echo "already_released=false" >> "$GITHUB_OUTPUT"
-
-      # -- SANITY CHECKS -------------------------------------------------------
-      - name: "Sanity: Pre-release validation"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.already_released != 'true'
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          ERRORS=0
-
-          PLATFORM="${{ steps.platform.outputs.platform }}"
-          MANIFEST="${{ steps.platform.outputs.manifest }}"
-          MOD_FILE="${{ steps.platform.outputs.mod_file }}"
-          echo "## Pre-Release Sanity Checks (${PLATFORM})" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-
-          # -- Version drift check (must pass before release) --------
-          README_VER=$(sed -n 's/.*VERSION:[[:space:]]*\([0-9][0-9]\.[0-9][0-9]\.[0-9][0-9]\).*/\1/p' README.md 2>/dev/null | head -1)
-          if [ "$README_VER" != "$VERSION" ]; then
-            echo "- Version drift: README says \`${README_VER}\` but releasing \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-            ERRORS=$((ERRORS+1))
-          else
-            echo "- Version consistent: \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-          fi
-
-          # Check CHANGELOG version matches
-          CL_VER=$(sed -n 's/.*VERSION:[[:space:]]*\([0-9][0-9]\.[0-9][0-9]\.[0-9][0-9]\).*/\1/p' CHANGELOG.md 2>/dev/null | head -1)
-          if [ -n "$CL_VER" ] && [ "$CL_VER" != "$VERSION" ]; then
-            echo "- CHANGELOG drift: \`${CL_VER}\` != \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-            ERRORS=$((ERRORS+1))
-          fi
-
-          # Check composer.json version if present
-          if [ -f "composer.json" ]; then
-            COMP_VER=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' composer.json 2>/dev/null | head -1)
-            if [ -n "$COMP_VER" ] && [ "$COMP_VER" != "$VERSION" ]; then
-              echo "- composer.json drift: \`${COMP_VER}\` != \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-              ERRORS=$((ERRORS+1))
-            fi
-          fi
-
-          # Common checks
-          if [ ! -f "LICENSE" ]; then
-            echo "- Missing LICENSE file" >> $GITHUB_STEP_SUMMARY
-            ERRORS=$((ERRORS+1))
-          else
-            echo "- LICENSE present" >> $GITHUB_STEP_SUMMARY
-          fi
-
-          if [ ! -d "src" ] && [ ! -d "htdocs" ]; then
-            echo "- Warning: No src/ or htdocs/ directory" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "- Source directory present" >> $GITHUB_STEP_SUMMARY
-          fi
-
-          # -- Platform-specific checks --------
-          case "$PLATFORM" in
-            joomla)
-              if [ -n "$MANIFEST" ]; then
-                XML_VER=$(sed -n 's/.*<version>\([^<]*\)<\/version>.*/\1/p' "$MANIFEST" 2>/dev/null | head -1)
-                if [ -n "$XML_VER" ] && [ "$XML_VER" != "$VERSION" ]; then
-                  echo "- Manifest drift: \`${XML_VER}\` != \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-                  ERRORS=$((ERRORS+1))
-                else
-                  echo "- Manifest version: \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-                fi
-                TYPE=$(sed -n 's/.*<extension[^>]*type="\([^"]*\)".*/\1/p' "$MANIFEST" 2>/dev/null)
-                echo "- Extension type: ${TYPE:-unknown}" >> $GITHUB_STEP_SUMMARY
-              else
-                echo "- No Joomla XML manifest (WaaS site)" >> $GITHUB_STEP_SUMMARY
-              fi ;;
-            dolibarr)
-              if [ -n "$MOD_FILE" ]; then
-                MOD_VER=$(sed -n "s/.*\\\$this->version = '\([^']*\)'.*/\1/p" "$MOD_FILE" 2>/dev/null | head -1)
-                if [ -n "$MOD_VER" ] && [ "$MOD_VER" != "$VERSION" ]; then
-                  echo "- Module drift: \`${MOD_VER}\` != \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-                  ERRORS=$((ERRORS+1))
-                else
-                  echo "- Module version: \`${VERSION}\`" >> $GITHUB_STEP_SUMMARY
-                fi
-              else
-                echo "- No mod*.class.php found" >> $GITHUB_STEP_SUMMARY
-                ERRORS=$((ERRORS+1))
-              fi
-              if [ ! -f "update.txt" ]; then
-                echo "- Missing update.txt" >> $GITHUB_STEP_SUMMARY
-                ERRORS=$((ERRORS+1))
-              fi ;;
-            *) echo "- Generic platform � no manifest checks" >> $GITHUB_STEP_SUMMARY ;;
-          esac
-
-          echo "" >> $GITHUB_STEP_SUMMARY
-          if [ "$ERRORS" -gt 0 ]; then
-            echo "**${ERRORS} error(s) — release may be incomplete**" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "**All sanity checks passed**" >> $GITHUB_STEP_SUMMARY
-          fi
-
-      # -- STEP 2: Create or update version/XX.YY archive branch ---------------
-      # Always runs — every version change on main archives to version/XX.YY
-      - name: "Step 2: Version archive branch"
-        if: steps.check.outputs.already_released != 'true'
-        run: |
-          BRANCH="${{ steps.version.outputs.branch }}"
-          IS_MINOR="${{ steps.version.outputs.is_minor }}"
-          PATCH="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          PATCH_NUM=$(echo "$PATCH" | awk -F. '{print $3}')
-
-          # Check if branch exists
-          if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
-            git push origin HEAD:"$BRANCH" --force
-            echo "Updated archive branch: ${BRANCH} (patch ${PATCH_NUM})" >> $GITHUB_STEP_SUMMARY
-          else
-            git checkout -b "$BRANCH" 2>/dev/null || git checkout "$BRANCH"
-            git push origin "$BRANCH" --force
-            echo "Created archive branch: ${BRANCH}" >> $GITHUB_STEP_SUMMARY
-          fi
-
-      # -- STEP 3: Set platform version ----------------------------------------
-      - name: "Step 3: Set platform version"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.already_released != 'true'
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          php /tmp/moko-platform-api/cli/version_set_platform.php \
-            --path . --version "$VERSION" --branch main
-
-      # -- STEP 4: Update version badges ----------------------------------------
-      - name: "Step 4: Update version badges"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.already_released != 'true'
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          php /tmp/moko-platform-api/cli/badge_update.php --path . --version "$VERSION"
-
-      # -- STEP 5: Write updates.xml (Joomla update server) ---------------------
-      - name: "Step 5: Write update stream"
-        id: updates
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.already_released != 'true'
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          CLI="/tmp/moko-platform-api/cli"
-
-          # Generate updates.xml with all stability channels + suffixed versions
-          # Also exports ext_element, ext_name, ext_type, ext_folder to GITHUB_OUTPUT
-          php $CLI/updates_xml_build.php \
-            --path . \
-            --version "$VERSION" \
-            --stability stable \
-            --gitea-url "${GITEA_URL}" \
-            --org "${GITEA_ORG}" \
-            --repo "${GITEA_REPO}" \
-            --github-output
-
-          echo "updates.xml: ${VERSION} (all channels updated to stable)" >> $GITHUB_STEP_SUMMARY
-
-      # -- Commit all changes ---------------------------------------------------
-      - name: Commit release changes
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.already_released != 'true'
-        run: |
-          if git diff --quiet && git diff --cached --quiet; then
-            echo "No changes to commit"
-            exit 0
-          fi
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-          # Set push URL with token for branch-protected repos
-          git remote set-url origin "https://jmiller:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
-          git add -A
-          git commit -m "chore(release): build ${VERSION} [skip ci]" \
-            --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>"
-          git push -u origin HEAD
-
-      # -- STEP 6: Create tag ---------------------------------------------------
-      - name: "Step 6: Create git tag"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.check.outputs.tag_exists != 'true' &&
-          steps.version.outputs.is_minor == 'true'
-        run: |
-          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
-          # Only create the major release tag if it doesn't exist yet
-          if ! git rev-parse "$RELEASE_TAG" >/dev/null 2>&1; then
-            git tag "$RELEASE_TAG"
-            git push origin "$RELEASE_TAG"
-            echo "Tag created: ${RELEASE_TAG}" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "Tag ${RELEASE_TAG} already exists" >> $GITHUB_STEP_SUMMARY
-          fi
-          echo "Tag: ${TAG}" >> $GITHUB_STEP_SUMMARY
-
-      # -- STEP 7: Create or update Gitea Release --------------------------------
-      - name: "Step 7: Gitea Release"
-        if: >-
-          steps.version.outputs.skip != 'true'
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
-          BRANCH="${{ steps.version.outputs.branch }}"
-          CLI="/tmp/moko-platform-api/cli"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
-          # Reuse metadata from Step 5
-          EXT_NAME="${{ steps.updates.outputs.ext_name }}"
-          TYPE_PREFIX="${{ steps.updates.outputs.type_prefix }}"
-          EXT_ELEMENT="${{ steps.updates.outputs.ext_element }}"
-          [ -z "$EXT_NAME" ] && EXT_NAME="${GITEA_REPO}"
-          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
-
-          RELEASE_NAME="${EXT_NAME} ${VERSION} (${TYPE_PREFIX}${EXT_ELEMENT}-${VERSION})"
-          NOTES=$(php $CLI/release_notes.php --path . --version "$VERSION" 2>/dev/null)
-          [ -z "$NOTES" ] && NOTES="Release ${VERSION}"
-
-          php $CLI/release_manage.php \
-            --action create \
-            --tag "$RELEASE_TAG" \
-            --name "$RELEASE_NAME" \
-            --body "## ${VERSION} ($(date +%Y-%m-%d))\n${NOTES}" \
-            --target "$BRANCH" \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "$API_BASE"
-
-          echo "Release created: ${RELEASE_NAME}" >> $GITHUB_STEP_SUMMARY
-
-      # -- STEP 8: Build package, upload, and update checksums -------------------
-      - name: "Step 8: Build package and upload"
-        if: >-
-          steps.version.outputs.skip != 'true'
-        run: |
-          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
-          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
-          CLI="/tmp/moko-platform-api/cli"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
-          # Build ZIP + tar.gz via CLI (handles single and multi-extension packages)
-          php $CLI/package_build.php --path . --version "$VERSION" --output-dir /tmp --github-output
-
-          # Read outputs from package_build
-          ZIP_NAME="${{ steps.updates.outputs.type_prefix }}${{ steps.updates.outputs.ext_element }}-${VERSION}.zip"
-          TAR_NAME="${{ steps.updates.outputs.type_prefix }}${{ steps.updates.outputs.ext_element }}-${VERSION}.tar.gz"
-
-          # Upload assets to release (handles dedup automatically)
-          php $CLI/release_manage.php \
-            --action upload \
-            --tag "$RELEASE_TAG" \
-            --files "/tmp/${ZIP_NAME},/tmp/${TAR_NAME}" \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "$API_BASE"
-
-          # Regenerate updates.xml with SHA-256 from built package
-          SHA256_ZIP=$(sha256sum "/tmp/${ZIP_NAME}" | cut -d' ' -f1)
-          php $CLI/updates_xml_build.php \
-            --path . \
-            --version "$VERSION" \
-            --stability stable \
-            --sha "$SHA256_ZIP" \
-            --gitea-url "${GITEA_URL}" \
-            --org "${GITEA_ORG}" \
-            --repo "${GITEA_REPO}"
-
-          # Commit updated updates.xml
-          git add updates.xml
-          git commit -m "chore(release): ZIP + tar.gz for ${VERSION} [skip ci]" \
-            --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>" || true
-          git push || true
-
-          # Sync updates.xml to main via API (may be on version/XX branch)
-          GA_TOKEN="${{ secrets.GA_TOKEN }}"
-          API="${GITEA_URL:-https://git.mokoconsulting.tech}/api/v1/repos/${{ github.repository }}"
-          FILE_SHA=$(curl -sf -H "Authorization: token ${GA_TOKEN}" \
-            "${API}/contents/updates.xml?ref=main" | jq -r '.sha // empty')
-          if [ -n "$FILE_SHA" ]; then
-            CONTENT=$(base64 -w0 updates.xml)
-            curl -sf -X PUT -H "Authorization: token ${GA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              "${API}/contents/updates.xml" \
-              -d "$(jq -n \
-                --arg content "$CONTENT" \
-                --arg sha "$FILE_SHA" \
-                --arg msg "chore: sync updates.xml ${VERSION} [skip ci]" \
-                --arg branch "main" \
-                '{content: $content, sha: $sha, message: $msg, branch: $branch}'
-              )" > /dev/null 2>&1 \
-              && echo "updates.xml synced to main via API" \
-              || echo "WARNING: failed to sync updates.xml to main"
-          fi
-
-          # Build release body with changelog + SHA
-          NOTES=$(php $CLI/release_notes.php --path . --version "$VERSION" 2>/dev/null)
-          SHA256_TAR=""
-          [ -f "/tmp/${TAR_NAME}" ] && SHA256_TAR=$(sha256sum "/tmp/${TAR_NAME}" | cut -d' ' -f1)
-
-          BODY="## ${VERSION} ($(date +%Y-%m-%d))\n\n${NOTES}\n\n---\n\n### Checksums\n\n"
-          BODY="${BODY}| File | SHA-256 |\n|------|--------|\n"
-          BODY="${BODY}| \`${ZIP_NAME}\` | \`${SHA256_ZIP}\` |\n"
-          [ -n "$SHA256_TAR" ] && BODY="${BODY}| \`${TAR_NAME}\` | \`${SHA256_TAR}\` |\n"
-
-          printf '%b' "$BODY" > /tmp/release_body.md
-          php $CLI/release_manage.php \
-            --action update-body \
-            --tag "$RELEASE_TAG" \
-            --body-file /tmp/release_body.md \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "$API_BASE"
-
-          echo "### Packages" >> $GITHUB_STEP_SUMMARY
-          echo "| Package | SHA-256 |" >> $GITHUB_STEP_SUMMARY
-          echo "|---------|---------|" >> $GITHUB_STEP_SUMMARY
-          echo "| \`${ZIP_NAME}\` | \`${SHA256_ZIP}\` |" >> $GITHUB_STEP_SUMMARY
-          echo "| \`${TAR_NAME}\` | \`${SHA256_TAR}\` |" >> $GITHUB_STEP_SUMMARY
+          php /tmp/moko-platform-api/cli/release_publish.php \
+            --path . --stability stable --bump minor --branch main \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}"

      # -- STEP 9: Mirror to GitHub (stable only) --------------------------------
      - name: "Step 9: Mirror release to GitHub"
        if: >-
          steps.version.outputs.skip != 'true' &&
-          steps.version.outputs.stability == 'stable' &&
-          secrets.GH_TOKEN != ''
+          secrets.GH_MIRROR_TOKEN != ''
        continue-on-error: true
-        env:
-          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
          RELEASE_TAG="${{ steps.version.outputs.release_tag }}"
-          MAJOR="${{ steps.version.outputs.major }}"
-          BRANCH="${{ steps.version.outputs.branch }}"
          GH_REPO="${{ vars.GH_MIRROR_REPO || github.repository }}"
-
-          NOTES=$(php /tmp/moko-platform-api/cli/release_notes.php --path . --version "$VERSION" 2>/dev/null || true)
-          [ -z "$NOTES" ] && NOTES="Release ${VERSION}"
-          echo "$NOTES" > /tmp/release_notes.md
-
-          EXISTING=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" "${GITEA_URL:-https://git.mokoconsulting.tech}/api/v1/repos/${{ github.repository }}/releases/tags/$RELEASE_TAG" 2>/dev/null | jq -r ".tag_name // empty" || true)
-
-          if [ -z "$EXISTING" ]; then
-            gh release create "$RELEASE_TAG" \
-              --repo "$GH_REPO" \
-              --title "v${MAJOR} (latest: ${VERSION})" \
-              --notes-file /tmp/release_notes.md \
-              --target "$BRANCH" || true
-          else
-            gh release edit "$RELEASE_TAG" \
-              --repo "$GH_REPO" \
-              --title "v${MAJOR} (latest: ${VERSION})" || true
-          fi
-
-          # Upload assets to GitHub mirror
-          for PKG in /tmp/${EXT_ELEMENT:-pkg}-${VERSION}.*; do
-            if [ -f "$PKG" ]; then
-              _RELID=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" "${GITEA_URL:-https://git.mokoconsulting.tech}/api/v1/repos/${{ github.repository }}/releases/tags/$RELEASE_TAG" 2>/dev/null | jq -r ".id // empty")
-              [ -n "$_RELID" ] && curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" -H "Content-Type: application/octet-stream" "${GITEA_URL:-https://git.mokoconsulting.tech}/api/v1/repos/${{ github.repository }}/releases/${_RELID}/assets?name=$(basename $PKG)" --data-binary "@$PKG" > /dev/null 2>&1 || true
-            fi
-          done
-          echo "GitHub mirror updated: ${GH_REPO} ${RELEASE_TAG}" >> $GITHUB_STEP_SUMMARY
+          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_TOKEN != ''
+          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_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git" 2>/dev/null || \
-            git remote set-url github "https://x-access-token:${{ secrets.GH_TOKEN }}@github.com/${GH_ORG}/${GH_NAME}.git"
+          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"

-      # -- Clean up lesser pre-releases (cascade) ---------------------------------
-      - name: "Delete lesser pre-release channels"
-        if: steps.version.outputs.skip != 'true'
-        continue-on-error: true
-        run: |
-          php /tmp/moko-platform-api/cli/release_cascade.php \
-            --stability stable \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
-      # -- STEP 11: Reset dev branch from main ------------------------------------
-      - name: "Step 11: Delete and recreate dev branch from main"
+      - 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.GA_TOKEN }}"
+          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}" \
@@ -584,30 +213,37 @@ jobs:
            "${API_BASE}/branches" \
            -d '{"new_branch_name":"dev","old_branch_name":"main"}' 2>/dev/null && echo "Recreated dev from main"

-          echo "Dev branch reset from main (keeps dev ahead after release)" >> $GITHUB_STEP_SUMMARY
+          echo "Pre-release branches cleaned, dev reset from main" >> $GITHUB_STEP_SUMMARY

-
-      # -- Dolibarr post-release: Reset dev version -----------------------------
-      - name: "Dolibarr: Reset dev version"
-        if: >-
-          steps.version.outputs.skip != 'true' &&
-          steps.platform.outputs.platform == 'dolibarr' &&
-          steps.platform.outputs.mod_file != ''
+      - 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.GA_TOKEN }}"
-          MOD_FILE="${{ steps.platform.outputs.mod_file }}"
-          ENCODED_PATH=$(echo "$MOD_FILE" | sed 's|^\./||' | python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read().strip()))")
-          FILE_RESP=$(curl -sf -H "Authorization: token ${TOKEN}" "${API_BASE}/contents/${ENCODED_PATH}?ref=dev" 2>/dev/null || true)
-          FILE_SHA=$(echo "$FILE_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('sha',''))" 2>/dev/null || true)
-          FILE_CONTENT=$(echo "$FILE_RESP" | python3 -c "import sys,json,base64; print(base64.b64decode(json.load(sys.stdin).get('content','')).decode())" 2>/dev/null || true)
-          if [ -n "$FILE_SHA" ] && [ -n "$FILE_CONTENT" ]; then
-            UPDATED=$(echo "$FILE_CONTENT" | sed "s/\$this->version = '[^']*'/\$this->version = 'development'/")
-            ENCODED=$(echo "$UPDATED" | base64 -w0)
-            curl -sf -X PUT -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" "${API_BASE}/contents/${ENCODED_PATH}" \
-              -d "$(jq -n --arg content \"$ENCODED\" --arg sha \"$FILE_SHA\" --arg msg \"chore(version): reset dev version [skip ci]\" --arg branch \"dev\" '{content:$content,sha:$sha,message:$msg,branch:$branch}')" > /dev/null 2>&1 || true
-          fi
+          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
@@ -1,213 +1,10 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-#
-# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Maintenance
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
-# PATH: /templates/workflows/cascade-dev.yml.template
-# VERSION: 02.00.00
-# BRIEF: Forward-merge main → all open branches after every push to main
-#
-# +========================================================================+
-# |                CASCADE MAIN → ALL BRANCHES                             |
-# +========================================================================+
-# |                                                                        |
-# |  Triggers on every push to main (PR merges, bot commits, etc.)         |
-# |                                                                        |
-# |  1. List all branches matching: dev, rc/*, beta/*, alpha/*             |
-# |  2. For each: create PR (main → branch), auto-merge if clean           |
-# |  3. On conflict: leave PR open for manual resolution                   |
-# |                                                                        |
-# +========================================================================+
-
-name: "Universal: Cascade Main → Dev"
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-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
-  pull-requests: write
-
+# DISABLED — auto-release Step 11 recreates dev from main after every release.
+# Cascade-dev is redundant and causes version conflicts when both main and dev
+# have different version numbers in templateDetails.xml / manifest.xml.
+name: "Cascade Main → Dev (DISABLED)"
+on: workflow_dispatch
 jobs:
-  cascade:
-    name: Cascade main → branches
+  noop:
    runs-on: ubuntu-latest
-    if: >-
-      !contains(github.event.head_commit.message, '[skip ci]') &&
-      !contains(github.event.head_commit.message, '[skip cascade]')
-
    steps:
-      - name: Discover target branches
-        id: branches
-        env:
-          GA_TOKEN: ${{ secrets.GA_TOKEN }}
-        run: |
-          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-
-          # Fetch all branches (paginated)
-          PAGE=1
-          ALL_BRANCHES=""
-          while true; do
-            BATCH=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/branches?page=${PAGE}&limit=50" \
-              | jq -r '.[].name // empty')
-            [ -z "$BATCH" ] && break
-            ALL_BRANCHES="$ALL_BRANCHES $BATCH"
-            PAGE=$((PAGE + 1))
-          done
-
-          # Filter to cascade targets: dev, dev/*, rc/*, beta/*, alpha/*
-          TARGETS=""
-          for BRANCH in $ALL_BRANCHES; do
-            case "$BRANCH" in
-              dev|dev/*|rc/*|beta/*|alpha/*)
-                TARGETS="$TARGETS $BRANCH"
-                ;;
-            esac
-          done
-
-          TARGETS=$(echo "$TARGETS" | xargs)  # trim whitespace
-
-          if [ -z "$TARGETS" ]; then
-            echo "targets=" >> "$GITHUB_OUTPUT"
-            echo "ℹ️  No cascade target branches found"
-          else
-            echo "targets=$TARGETS" >> "$GITHUB_OUTPUT"
-            COUNT=$(echo "$TARGETS" | wc -w)
-            echo "📋 Found ${COUNT} target branch(es): ${TARGETS}"
-          fi
-
-      - name: Cascade to all target branches
-        if: steps.branches.outputs.targets != ''
-        env:
-          GA_TOKEN: ${{ secrets.GA_TOKEN }}
-        run: |
-          API="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          SHORT_SHA="${GITHUB_SHA:0:7}"
-          TARGETS="${{ steps.branches.outputs.targets }}"
-
-          SUCCESS=0
-          CONFLICTS=0
-          SKIPPED=0
-          FAILED=0
-
-          for BRANCH in $TARGETS; do
-            echo ""
-            echo "═══ main → ${BRANCH} ═══"
-
-            # Check if branch is already up to date
-            ENCODED_BRANCH=$(echo "$BRANCH" | sed 's|/|%2F|g')
-            RESPONSE=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/compare/${ENCODED_BRANCH}...main")
-
-            AHEAD=$(echo "$RESPONSE" | jq '.total_commits // 0')
-
-            if [ "$AHEAD" -eq 0 ]; then
-              echo "  ✅ Already up to date"
-              SKIPPED=$((SKIPPED + 1))
-              continue
-            fi
-
-            echo "  ℹ️  main is ${AHEAD} commit(s) ahead"
-
-            # Check for existing cascade PR
-            EXISTING=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/pulls?state=open&head=${GITEA_ORG}:main&base=${ENCODED_BRANCH}&limit=1")
-
-            EXISTING_COUNT=$(echo "$EXISTING" | jq 'length')
-            PR_NUMBER=""
-
-            if [ "$EXISTING_COUNT" -gt 0 ]; then
-              PR_NUMBER=$(echo "$EXISTING" | jq -r '.[0].number')
-              echo "  ℹ️  Reusing existing PR #${PR_NUMBER}"
-            else
-              # Create cascade PR
-              PR_RESPONSE=$(curl -sS -w "\n%{http_code}" \
-                -X POST \
-                -H "Authorization: token ${GA_TOKEN}" \
-                -H "Content-Type: application/json" \
-                -d "{
-                  \"title\": \"chore: cascade main → ${BRANCH} (${SHORT_SHA}) [skip ci]\",
-                  \"body\": \"## Automatic cascade\\n\\nForward-merging \`main\` (${SHORT_SHA}) into \`${BRANCH}\`.\\n\\nIf conflicts exist, resolve manually and merge.\\n\\n> Auto-created by **Cascade Main → Dev**.\",
-                  \"head\": \"main\",
-                  \"base\": \"${BRANCH}\"
-                }" \
-                "${API}/pulls")
-
-              HTTP_CODE=$(echo "$PR_RESPONSE" | tail -1)
-              BODY=$(echo "$PR_RESPONSE" | sed '$d')
-              PR_NUMBER=$(echo "$BODY" | jq -r '.number // empty')
-
-              if [ "$HTTP_CODE" != "201" ] || [ -z "$PR_NUMBER" ]; then
-                MSG=$(echo "$BODY" | jq -r '.message // .' 2>/dev/null | head -1)
-                echo "  ❌ Failed to create PR (HTTP ${HTTP_CODE}): ${MSG}"
-                FAILED=$((FAILED + 1))
-                continue
-              fi
-
-              echo "  ✅ Created PR #${PR_NUMBER}"
-            fi
-
-            # Try auto-merge
-            PR_DATA=$(curl -sS \
-              -H "Authorization: token ${GA_TOKEN}" \
-              "${API}/pulls/${PR_NUMBER}")
-
-            MERGEABLE=$(echo "$PR_DATA" | jq -r '.mergeable // false')
-
-            if [ "$MERGEABLE" != "true" ]; then
-              echo "  ⚠️  Conflicts — PR #${PR_NUMBER} left open"
-              CONFLICTS=$((CONFLICTS + 1))
-              continue
-            fi
-
-            MERGE_RESPONSE=$(curl -sS -w "\n%{http_code}" \
-              -X POST \
-              -H "Authorization: token ${GA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              -d "{
-                \"Do\": \"merge\",
-                \"merge_message_field\": \"chore: cascade main → ${BRANCH} [skip ci]\",
-                \"delete_branch_after_merge\": false
-              }" \
-              "${API}/pulls/${PR_NUMBER}/merge")
-
-            MERGE_HTTP=$(echo "$MERGE_RESPONSE" | tail -1)
-
-            if [ "$MERGE_HTTP" = "200" ] || [ "$MERGE_HTTP" = "204" ]; then
-              echo "  ✅ Merged — ${BRANCH} is in sync"
-              SUCCESS=$((SUCCESS + 1))
-            else
-              MERGE_BODY=$(echo "$MERGE_RESPONSE" | sed '$d')
-              echo "  ⚠️  Merge failed (HTTP ${MERGE_HTTP}) — PR #${PR_NUMBER} left open"
-              CONFLICTS=$((CONFLICTS + 1))
-            fi
-          done
-
-          # Summary
-          echo ""
-          echo "════════════════════════════════════════"
-          echo "  ✅ Merged:    ${SUCCESS}"
-          echo "  ⚠️  Conflicts: ${CONFLICTS}"
-          echo "  ⏭️  Up to date: ${SKIPPED}"
-          echo "  ❌ Failed:    ${FAILED}"
-          echo "════════════════════════════════════════"
-
-          if [ "$FAILED" -gt 0 ]; then
-            exit 1
-          fi
+      - run: echo "Cascade disabled — auto-release handles dev recreation"
@@ -43,9 +43,9 @@ jobs:

      - name: Clone MokoStandards
        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' }}
+          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN || secrets.MOKOGITEA_TOKEN || github.token }}
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN || secrets.MOKOGITEA_TOKEN || github.token }}
+          MOKO_CLONE_HOST: ${{ secrets.MOKOGITEA_TOKEN && 'git.mokoconsulting.tech/MokoConsulting' || 'github.com/mokoconsulting-tech' }}
        run: |
          git clone --depth 1 --branch main --quiet \
            "https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/MokoStandards-API.git" \
@@ -53,7 +53,7 @@ jobs:

      - name: Install dependencies
        env:
-          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GA_TOKEN || github.token }}"}}'
+          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.MOKOGITEA_TOKEN || github.token }}"}}'
        run: |
          if [ -f "composer.json" ]; then
            composer install \
@@ -346,7 +346,7 @@ jobs:

      - name: Install dependencies
        env:
-          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GA_TOKEN || github.token }}"}}'
+          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.MOKOGITEA_TOKEN || github.token }}"}}'
        run: |
          if [ -f "composer.json" ]; then
            composer install \
@@ -391,7 +391,7 @@ jobs:

      - name: Install dependencies
        env:
-          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GA_TOKEN || github.token }}"}}'
+          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.MOKOGITEA_TOKEN || github.token }}"}}'
        run: |
          if [ -f "composer.json" ]; then
            composer install --no-interaction --prefer-dist --optimize-autoloader
@@ -4,8 +4,8 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Maintenance
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
+# INGROUP: moko-platform.Maintenance
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /.gitea/workflows/cleanup.yml
 # VERSION: 01.00.00
 # BRIEF: Scheduled cleanup — delete merged branches and old workflow runs
@@ -33,17 +33,17 @@ jobs:
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
-          token: ${{ secrets.GA_TOKEN }}
+          token: ${{ secrets.MOKOGITEA_TOKEN }}

      - name: Delete merged branches
        env:
-          GA_TOKEN: ${{ secrets.GA_TOKEN }}
+          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
        run: |
          echo "=== Merged Branch Cleanup ==="
          API="${GITEA_URL}/api/v1/repos/${{ github.repository }}"

          # List branches via API
-          BRANCHES=$(curl -sS -H "Authorization: token ${GA_TOKEN}" \
+          BRANCHES=$(curl -sS -H "Authorization: token ${GITEA_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 ${GA_TOKEN}" \
+              curl -sS -X DELETE -H "Authorization: token ${GITEA_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.GA_TOKEN }}
+          GA_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
        run: |
          echo "=== Workflow Run Cleanup ==="
          API="${GITEA_URL}/api/v1/repos/${{ github.repository }}"
          CUTOFF=$(date -d "30 days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -v-30d +%Y-%m-%dT%H:%M:%SZ)

          # Get old completed runs
-          RUNS=$(curl -sS -H "Authorization: token ${GA_TOKEN}" \
+          RUNS=$(curl -sS -H "Authorization: token ${GITEA_TOKEN}" \
            "${API}/actions/runs?status=completed&limit=50" | \
            jq -r ".workflow_runs[] | select(.created_at < \"${CUTOFF}\") | .id" 2>/dev/null)

          DELETED=0
          for RUN_ID in $RUNS; do
-            curl -sS -X DELETE -H "Authorization: token ${GA_TOKEN}" \
+            curl -sS -X DELETE -H "Authorization: token ${GITEA_TOKEN}" \
              "${API}/actions/runs/${RUN_ID}" 2>/dev/null || true
            DELETED=$((DELETED + 1))
          done
@@ -1,126 +0,0 @@
-# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
-#
-# SPDX-License-Identifier: GPL-3.0-or-later
-#
-# FILE INFORMATION
-# DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.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
@@ -4,8 +4,8 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Security
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
+# INGROUP: moko-platform.Security
+# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
 # PATH: /templates/workflows/gitleaks.yml.template
 # VERSION: 01.00.00
 # BRIEF: Secret scanning — detect leaked credentials, API keys, and tokens
@@ -4,8 +4,8 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Notifications
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
+# INGROUP: moko-platform.Notifications
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /.gitea/workflows/notify.yml
 # VERSION: 01.00.00
 # BRIEF: Push notifications via ntfy on release success or workflow failure
@@ -18,7 +18,6 @@ on:
      - "Joomla Build & Release"
      - "Joomla Extension CI"
      - "Deploy"
-      - "Cascade Main → Dev"
    types:
      - completed

@@ -4,8 +4,8 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.CI
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
+# 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
@@ -52,22 +52,22 @@ jobs:
                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
              ;;
-            alpha/*|beta/*)
-              if [ "$BASE" != "dev" ]; then
-                ALLOWED=false
-                REASON="Pre-release branches must target 'dev', not '${BASE}'"
-              fi
-              ;;
-            rc/*)
+            rc)
              if [ "$BASE" != "main" ]; then
                ALLOWED=false
-                REASON="Release candidate branches must target 'main', not '${BASE}'"
+                REASON="RC branch can only merge into 'main', not '${BASE}'"
              fi
              ;;
            dev)
@@ -108,7 +108,9 @@ jobs:
      - name: Detect platform
        id: platform
        run: |
-          PLATFORM=$(cat .mokogitea/.moko-platform 2>/dev/null | tr -d '[:space:]')
+          # 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"

@@ -181,6 +183,28 @@ jobs:
              ;;
          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"
@@ -192,3 +216,21 @@ jobs:
          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
@@ -8,11 +8,16 @@
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /templates/workflows/universal/pre-release.yml.template
 # VERSION: 05.01.00
-# BRIEF: Manual pre-release — builds dev/alpha/beta/rc packages from any branch
+# BRIEF: Manual pre-release -- builds dev/alpha/beta/rc packages from any branch

 name: "Universal: Pre-Release"

 on:
+  pull_request:
+    types: [opened, ready_for_review, closed]
+    branches:
+      - dev
+      - main
  workflow_dispatch:
    inputs:
      stability:
@@ -35,44 +40,70 @@ env:

 jobs:
  build:
-    name: "Build Pre-Release (${{ inputs.stability }})"
+    name: "Build Pre-Release (${{ inputs.stability || (github.event.pull_request.base.ref == 'main' && 'release-candidate') || 'development' }})"
    runs-on: release
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'dev') ||
+      (github.event.action != 'closed' && github.event.pull_request.base.ref == 'main')

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
-          token: ${{ secrets.GA_TOKEN }}
+          token: ${{ secrets.MOKOGITEA_TOKEN }}

      - name: Setup moko-platform tools
        env:
-          MOKO_CLONE_TOKEN: ${{ secrets.GA_TOKEN }}
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-          COMPOSER_AUTH: '{"github-oauth":{"github.com":"${{ secrets.GH_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-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
+          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: |
-          PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*/\1/p' .mokogitea/manifest.xml 2>/dev/null | head -1 | tr -d '[:space:]')
-          [ -z "$PLATFORM" ] && PLATFORM=$(sed -n 's/.*<platform>\([^<]*\)<\/platform>.*/\1/p' .gitea/manifest.xml 2>/dev/null | head -1 | tr -d '[:space:]')
-          [ -z "$PLATFORM" ] && PLATFORM="generic"
-          echo "platform=$PLATFORM" >> "$GITHUB_OUTPUT"
+          php ${MOKO_CLI}/manifest_read.php --path . --github-output
+
+      - name: Rename branch to rc on PR draft to main
+        if: >-
+          github.event.action != 'closed' &&
+          github.event.pull_request.base.ref == 'main'
+        run: |
+          HEAD_BRANCH="${{ github.event.pull_request.head.ref }}"
+          if [ "$HEAD_BRANCH" != "rc" ]; then
+            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 checkout -b rc
+            git push origin rc 2>&1 || true
+            # Update PR head branch via API
+            curl -s -X PATCH \
+              -H "Authorization: token ${{ secrets.MOKOGITEA_TOKEN }}" \
+              -H "Content-Type: application/json" \
+              -d "{\"head\": \"rc\"}" \
+              "${GITEA_URL}/api/v1/repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}" || true
+          fi

      - name: Resolve metadata and bump version
        id: meta
        run: |
-          CLI="/tmp/moko-platform-api/cli"
-          STABILITY="${{ inputs.stability }}"
+          # Auto-detect RC when PR targets main
+          if [ "${{ github.event.pull_request.base.ref }}" = "main" ] && [ "${{ github.event.action }}" != "closed" ]; then
+            STABILITY="release-candidate"
+          else
+            STABILITY="${{ inputs.stability || 'development' }}"
+          fi

          case "$STABILITY" in
            development)        SUFFIX="-dev";   TAG="development" ;;
@@ -81,107 +112,100 @@ jobs:
            release-candidate)  SUFFIX="-rc";    TAG="release-candidate" ;;
          esac

-          # Bump patch version via CLI
-          CURRENT=$(php $CLI/version_read.php --path . 2>/dev/null)
-          [ -z "$CURRENT" ] && CURRENT="00.00.00"
-          php $CLI/version_bump.php --path .
-          VERSION=$(php $CLI/version_read.php --path . 2>/dev/null)
-          echo "Bumping: ${CURRENT} → ${VERSION} (patch)"
+          # Read current version (bump already handled by push workflow)
+          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null)
+          [ -z "$VERSION" ] && VERSION="00.00.01"

-          # Set platform-specific version with stability suffix
-          php $CLI/version_set_platform.php \
-            --path . --version "$VERSION" --stability "$STABILITY" --branch "${{ github.ref_name }}"
+          # Strip any existing suffix from version before applying stability
+          VERSION=$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
+
+          php ${MOKO_CLI}/version_set_platform.php \
+            --path . --version "$VERSION" --branch "${{ github.ref_name }}" --stability "$STABILITY" 2>/dev/null || true
+
+          # Verify version consistency across all files
+          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
+
+          # Update VERSION variable with suffix
+          if [ -n "$SUFFIX" ]; then
+            VERSION="${VERSION}${SUFFIX}"
+          fi

          # Commit version bump
          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
          git config --local user.name "gitea-actions[bot]"
-          git remote set-url origin "https://jmiller:${{ secrets.GA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"
+          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): bump ${CURRENT} → ${VERSION}${SUFFIX} [skip ci]"
+            git commit -m "chore(version): pre-release bump to ${VERSION} [skip ci]"
            git push origin HEAD 2>&1
          }

+          # Auto-detect element via manifest_element.php
+          php ${MOKO_CLI}/manifest_element.php \
+            --path . --version "$VERSION" --stability "$STABILITY" \
+            --repo "${GITEA_REPO}" --github-output
+
+          # Read back element outputs
+          EXT_ELEMENT=$(grep '^ext_element=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)
+          ZIP_NAME=$(grep '^zip_name=' "$GITHUB_OUTPUT" | tail -1 | cut -d= -f2)
+          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
+          [ -z "$ZIP_NAME" ] && ZIP_NAME="${EXT_ELEMENT}-${VERSION}.zip"
+
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "zip_name=${ZIP_NAME}" >> "$GITHUB_OUTPUT"
+          echo "ext_element=${EXT_ELEMENT}" >> "$GITHUB_OUTPUT"

-      - name: Build package
+          echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
+
+      - name: Create release
+        id: release
+        run: |
+          TAG="${{ steps.meta.outputs.tag }}"
+          VERSION="${{ steps.meta.outputs.version }}"
+          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          php ${MOKO_CLI}/release_create.php \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${{ secrets.MOKOGITEA_TOKEN }}" --api-base "$API_BASE" \
+            --repo "${GITEA_REPO}" --branch "${{ github.ref_name }}" --prerelease
+
+      - name: Build package and upload
        id: package
        run: |
-          CLI="/tmp/moko-platform-api/cli"
          VERSION="${{ steps.meta.outputs.version }}"
-          SUFFIX="${{ steps.meta.outputs.suffix }}"
-
-          # Build ZIP + tar.gz via CLI (handles type prefix, excludes, multi-extension packages)
-          php $CLI/package_build.php \
-            --path . \
-            --version "${VERSION}${SUFFIX}" \
-            --output-dir build \
-            --github-output
-
-      - name: Create release and upload
-        run: |
-          CLI="/tmp/moko-platform-api/cli"
-          VERSION="${{ steps.meta.outputs.version }}"
-          SUFFIX="${{ steps.meta.outputs.suffix }}"
          TAG="${{ steps.meta.outputs.tag }}"
-          STABILITY="${{ steps.meta.outputs.stability }}"
          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          EXT_ELEMENT="${{ steps.package.outputs.ext_element }}"
-          [ -z "$EXT_ELEMENT" ] && EXT_ELEMENT=$(echo "${GITEA_REPO}" | tr '[:upper:]' '[:lower:]' | tr -d ' -')
-
-          SHA256="${{ steps.package.outputs.sha256_zip }}"
-          ZIP_PATH="${{ steps.package.outputs.zip_path }}"
-          TAR_PATH="${{ steps.package.outputs.tar_path }}"
-
-          # Create release
-          php $CLI/release_manage.php \
-            --action create \
-            --tag "$TAG" \
-            --name "${EXT_ELEMENT} ${VERSION}${SUFFIX} (${STABILITY})" \
-            --body "## ${VERSION}${SUFFIX} ($(date +%Y-%m-%d))\n**Channel:** ${STABILITY}\n**SHA-256:** \`${SHA256}\`" \
-            --target "${{ github.ref_name }}" \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "$API_BASE"
-
-          # Upload assets
-          FILES="${ZIP_PATH}"
-          [ -f "$TAR_PATH" ] && FILES="${FILES},${TAR_PATH}"
-          php $CLI/release_manage.php \
-            --action upload \
-            --tag "$TAG" \
-            --files "$FILES" \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "$API_BASE"
+          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: |
-          CLI="/tmp/moko-platform-api/cli"
          VERSION="${{ steps.meta.outputs.version }}"
          STABILITY="${{ steps.meta.outputs.stability }}"
          SHA256="${{ steps.package.outputs.sha256_zip }}"

-          # Map stability names
-          case "$STABILITY" in
-            release-candidate) CLI_STABILITY="rc" ;;
-            *) CLI_STABILITY="$STABILITY" ;;
-          esac
+          if [ ! -f "updates.xml" ]; then
+            echo "No updates.xml -- skipping"
+            exit 0
+          fi

-          # Generate updates.xml with stability-suffixed versions
-          php $CLI/updates_xml_build.php \
-            --path . \
-            --version "$VERSION" \
-            --stability "$CLI_STABILITY" \
-            --sha "$SHA256" \
-            --gitea-url "${GITEA_URL}" \
-            --org "${GITEA_ORG}" \
-            --repo "${GITEA_REPO}"
+          SHA_FLAG=""
+          [ -n "$SHA256" ] && SHA_FLAG="--sha ${SHA256}"
+
+          php ${MOKO_CLI}/updates_xml_build.php \
+            --path . --version "${VERSION}" --stability "${STABILITY}" \
+            --gitea-url "${GITEA_URL}" --org "${GITEA_ORG}" --repo "${GITEA_REPO}" \
+            ${SHA_FLAG}

          # Commit and push
          if ! git diff --quiet updates.xml 2>/dev/null; then
+            git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
+            git config --local user.name "gitea-actions[bot]"
            git add updates.xml
            git commit -m "chore: update ${STABILITY} channel ${VERSION} [skip ci]"
            git push origin HEAD 2>&1 || echo "WARNING: push failed"
@@ -196,9 +220,9 @@ jobs:

          for BRANCH in main dev; do
            [ "$BRANCH" = "$CURRENT_BRANCH" ] && continue
-            echo "Syncing updates.xml → ${BRANCH}"
+            echo "Syncing updates.xml -> ${BRANCH}"
            git fetch origin "${BRANCH}" 2>/dev/null || continue
-            git checkout "origin/${BRANCH}" -- . 2>/dev/null || continue
+            git checkout "origin/${BRANCH}" -- updates.xml 2>/dev/null || continue
            git checkout "${CURRENT_BRANCH}" -- updates.xml
            if ! git diff --quiet updates.xml 2>/dev/null; then
              git add updates.xml
@@ -211,15 +235,26 @@ jobs:
      - 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 }}"
-
-          # Map workflow stability names to CLI names
-          case "$STABILITY" in
-            release-candidate) CLI_STABILITY="rc" ;;
-            *) CLI_STABILITY="$STABILITY" ;;
-          esac
-
-          php /tmp/moko-platform-api/cli/release_cascade.php \
-            --stability "$CLI_STABILITY" \
-            --token "${{ secrets.GA_TOKEN }}" \
-            --api-base "${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
+          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
@@ -7,18 +7,14 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Validation
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
+# INGROUP: moko-platform.Validation
+# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/moko-platform
 # PATH: /templates/workflows/joomla/repo_health.yml.template
 # VERSION: 04.06.00
 # BRIEF: Enforces repository guardrails by validating release configuration, scripts governance, tooling availability, and core repository health artifacts.
 # ============================================================================

-name: "Joomla: Repo Health"
-
-concurrency:
-  group: repo-health-${{ github.repository }}-${{ github.ref }}
-  cancel-in-progress: true
+name: "Generic: Repo Health"

 defaults:
  run:
@@ -53,7 +49,7 @@ env:
  SCRIPTS_ALLOWED_DIRS: scripts,scripts/fix,scripts/lib,scripts/release,scripts/run,scripts/validate

  # Repo health policy
-  REPO_REQUIRED_ARTIFACTS: README.md,LICENSE,CHANGELOG.md,CONTRIBUTING.md,CODE_OF_CONDUCT.md,.gitea/workflows/
+  REPO_REQUIRED_ARTIFACTS: README.md,LICENSE,CHANGELOG.md,CONTRIBUTING.md,CODE_OF_CONDUCT.md,.mokogitea/workflows/
  REPO_OPTIONAL_FILES: SECURITY.md,GOVERNANCE.md,.editorconfig,.gitattributes,.gitignore,README.md,docs/
  REPO_DISALLOWED_DIRS:
  REPO_DISALLOWED_FILES: TODO.md,todo.md
@@ -64,7 +60,7 @@ env:
  # File / directory variables
  DOCS_INDEX: docs/docs-index.md
  SCRIPT_DIR: scripts
-  WORKFLOWS_DIR: .gitea/workflows
+  WORKFLOWS_DIR: .mokogitea/workflows
  SHELLCHECK_PATTERN: '*.sh'
  SPDX_FILE_GLOBS: '*.sh,*.php,*.js,*.ts,*.css,*.xml,*.yml,*.yaml'
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
@@ -85,7 +81,7 @@ jobs:
      - name: Check actor permission (admin only)
        id: perm
        env:
-          TOKEN: ${{ secrets.GA_TOKEN || secrets.GA_TOKEN || github.token }}
+          TOKEN: ${{ secrets.MOKOGITEA_TOKEN || secrets.MOKOGITEA_TOKEN || github.token }}
          REPO: ${{ github.repository }}
          ACTOR: ${{ github.actor }}
        run: |
@@ -288,7 +284,7 @@ jobs:
            exit 0
          fi

-          IFS=',' read -r -a required_dirs <<< "${SCRIPTS_REQUIRED_DIRS}"
+          if [ -n "${SCRIPTS_REQUIRED_DIRS:-}" ]; then IFS=',' read -r -a required_dirs <<< "${SCRIPTS_REQUIRED_DIRS}"; else required_dirs=(); fi
          IFS=',' read -r -a allowed_dirs <<< "${SCRIPTS_ALLOWED_DIRS}"

          missing_dirs=()
@@ -392,23 +388,27 @@ jobs:
            exit 0
          fi

-          # Source directory: src/ or htdocs/ (either is valid)
+          IFS=',' read -r -a required_artifacts <<< "${REPO_REQUIRED_ARTIFACTS}"
+          IFS=',' read -r -a optional_files <<< "${REPO_OPTIONAL_FILES}"
+          if [ -n "${REPO_DISALLOWED_DIRS:-}" ]; then IFS=',' read -r -a disallowed_dirs <<< "${REPO_DISALLOWED_DIRS}"; else disallowed_dirs=(); fi
+          IFS=',' read -r -a disallowed_files <<< "${REPO_DISALLOWED_FILES:-}"
+
+          missing_required=()
+          missing_optional=()
+
+          # Source directory: src/ or htdocs/ (either is valid for extension repos)
+          SOURCE_DIR=""
          if [ -d "src" ]; then
            SOURCE_DIR="src"
          elif [ -d "htdocs" ]; then
            SOURCE_DIR="htdocs"
+          elif [ -d "deploy" ] || [ -d "cli" ] || [ -d "monitoring" ]; then
+            # Platform/tooling repos don't need src/
+            SOURCE_DIR=""
          else
            missing_required+=("src/ or htdocs/ (source directory required)")
          fi

-          IFS=',' read -r -a required_artifacts <<< "${REPO_REQUIRED_ARTIFACTS}"
-          IFS=',' read -r -a optional_files <<< "${REPO_OPTIONAL_FILES}"
-          IFS=',' read -r -a disallowed_dirs <<< "${REPO_DISALLOWED_DIRS}"
-          IFS=',' read -r -a disallowed_files <<< "${REPO_DISALLOWED_FILES}"
-
-          missing_required=()
-          missing_optional=()
-
          for item in "${required_artifacts[@]}"; do
            if printf '%s' "${item}" | grep -q '/$'; then
              d="${item%/}"
@@ -450,12 +450,8 @@ jobs:
            fi
          done < <(git branch -r --list 'origin/dev*' | sed 's/^ *//')

-          if [ "${#dev_paths[@]}" -eq 0 ]; then
-            missing_required+=("dev/* branch (e.g. dev/01.00.00)")
-          fi
-
-          if [ "${#dev_branches[@]}" -gt 0 ]; then
-            missing_required+=("invalid branch dev (must be dev/<version>)")
+          if [ "${#dev_paths[@]}" -eq 0 ] && [ "${#dev_branches[@]}" -eq 0 ]; then
+            missing_required+=("dev or dev/* branch")
          fi

          content_warnings=()
@@ -481,26 +477,7 @@ jobs:
          export MISSING_OPTIONAL="$(printf '%s\n' "${missing_optional[@]:-}")"
          export CONTENT_WARNINGS="$(printf '%s\n' "${content_warnings[@]:-}")"

-          report_json="$(python3 - <<'PY'
-          import json
-          import os
-
-          profile = os.environ.get('PROFILE_RAW') or 'all'
-
-          missing_required = os.environ.get('MISSING_REQUIRED', '').splitlines() if os.environ.get('MISSING_REQUIRED') else []
-          missing_optional = os.environ.get('MISSING_OPTIONAL', '').splitlines() if os.environ.get('MISSING_OPTIONAL') else []
-          content_warnings = os.environ.get('CONTENT_WARNINGS', '').splitlines() if os.environ.get('CONTENT_WARNINGS') else []
-
-          out = {
-            'profile': profile,
-            'missing_required': [x for x in missing_required if x],
-            'missing_optional': [x for x in missing_optional if x],
-            'content_warnings': [x for x in content_warnings if x],
-          }
-
-          print(json.dumps(out, indent=2))
-          PY
-          )"
+          report_json=$(printf '{"profile":"%s","missing_required":%d,"missing_optional":%d,"content_warnings":%d}'             "$profile" "${#missing_required[@]}" "${#missing_optional[@]}" "${#content_warnings[@]}")

          {
            printf '%s\n' '### Repository health'
@@ -578,12 +555,14 @@ jobs:
            joomla_findings+=("updates.xml missing in root (required for Joomla update server)")
          fi

-          INDEX_DIRS=("${SOURCE_DIR}" "${SOURCE_DIR}/admin" "${SOURCE_DIR}/site")
-          for dir in "${INDEX_DIRS[@]}"; do
-            if [ -d "${dir}" ] && [ ! -f "${dir}/index.html" ]; then
-              joomla_findings+=("${dir}/index.html missing (directory listing protection)")
-            fi
-          done
+          if [ -n "${SOURCE_DIR}" ]; then
+            INDEX_DIRS=("${SOURCE_DIR}" "${SOURCE_DIR}/admin" "${SOURCE_DIR}/site")
+            for dir in "${INDEX_DIRS[@]}"; do
+              if [ -d "${dir}" ] && [ ! -f "${dir}/index.html" ]; then
+                joomla_findings+=("${dir}/index.html missing (directory listing protection)")
+              fi
+            done
+          fi

          if [ "${#joomla_findings[@]}" -gt 0 ]; then
            {
@@ -629,43 +608,29 @@ jobs:
            fi

            if [ -f "${DOCS_INDEX}" ]; then
-              missing_links="$(python3 - <<'PY'
-              import os
-              import re
-
-              idx = os.environ.get('DOCS_INDEX', 'docs/docs-index.md')
-              base = os.getcwd()
-
-              bad = []
-              pat = re.compile(r'\[[^\]]+\]\(([^)]+)\)')
-
-              with open(idx, 'r', encoding='utf-8') as f:
-                for line in f:
-                  for m in pat.findall(line):
-                    link = m.strip()
-                    if link.startswith('http://') or link.startswith('https://') or link.startswith('#') or link.startswith('mailto:'):
-                      continue
-                    if link.startswith('/'):
-                      rel = link.lstrip('/')
-                    else:
-                      rel = os.path.normpath(os.path.join(os.path.dirname(idx), link))
-                    rel = rel.split('#', 1)[0]
-                    rel = rel.split('?', 1)[0]
-                    if not rel:
-                      continue
-                    p = os.path.join(base, rel)
-                    if not os.path.exists(p):
-                      bad.append(rel)
-
-              print('\n'.join(sorted(set(bad))))
-              PY
-              )"
+              missing_links=""
+              while IFS= read -r docline; do
+                for link in $(echo "$docline" | grep -oE '\]\([^)]+\)' | sed 's/\](//' | sed 's/)$//' || true); do
+                  case "$link" in http://*|https://*|"#"*|mailto:*) continue ;; esac
+                  linkpath="${link%%#*}"
+                  linkpath="${linkpath%%\?*}"
+                  [ -z "$linkpath" ] && continue
+                  if [ "${linkpath:0:1}" = "/" ]; then
+                    testpath="${linkpath#/}"
+                  else
+                    testpath="$(dirname "${DOCS_INDEX}")/${linkpath}"
+                  fi
+                  [ ! -e "$testpath" ] && missing_links="${missing_links}${testpath} "
+                done
+              done < "${DOCS_INDEX}"
              if [ -n "${missing_links}" ]; then
                extended_findings+=("docs/docs-index.md contains broken relative links")
                {
                  printf '%s\n' '### Docs index link integrity'
                  printf '%s\n' 'Broken relative links:'
-                  while IFS= read -r l; do [ -n "${l}" ] && printf '%s\n' "- ${l}"; done <<< "${missing_links}"
+                  for bl in ${missing_links}; do
+                    printf '%s\n' "- ${bl}"
+                  done
                  printf '\n'
                } >> "${GITHUB_STEP_SUMMARY}"
              fi
@@ -764,3 +729,41 @@ jobs:
          fi

          printf '%s\n' 'Repository health guardrails passed.' >> "${GITHUB_STEP_SUMMARY}"
+
+
+  site-health:
+    name: Site Health
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+
+      - name: Uptime check
+        if: env.URLS != ''
+        run: |
+          echo "$URLS" > /tmp/urls.txt
+          php monitoring/uptime-probe.php --urls /tmp/urls.txt --timeout 15 || echo "::warning::Some sites are down"
+          rm -f /tmp/urls.txt
+        env:
+          URLS: ${{ vars.MONITORED_URLS }}
+
+      - name: SSL certificate check
+        if: env.DOMAINS != ''
+        run: |
+          echo "$DOMAINS" > /tmp/domains.txt
+          php monitoring/ssl-check.php --domains /tmp/domains.txt --warn-days 30 || echo "::warning::SSL certificates expiring soon"
+          rm -f /tmp/domains.txt
+        env:
+          DOMAINS: ${{ vars.MONITORED_DOMAINS }}
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "### Site Health" >> $GITHUB_STEP_SUMMARY
+          echo "Uptime and SSL checks completed." >> $GITHUB_STEP_SUMMARY
+
@@ -4,8 +4,8 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Security
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards
+# INGROUP: moko-platform.Security
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 # PATH: /.gitea/workflows/security-audit.yml
 # VERSION: 01.00.00
 # BRIEF: Dependency vulnerability scanning for composer and npm packages
@@ -80,3 +80,19 @@ 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 }}
+
@@ -4,20 +4,18 @@
 #
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
-# INGROUP: MokoStandards.Joomla
-# REPO: https://git.mokoconsulting.tech/mokoconsulting-tech/MokoStandards-API
-# PATH: /templates/workflows/joomla/update-server.yml.template
-# VERSION: 04.06.00
-# BRIEF: Update Joomla update server XML feed with stable/rc/dev entries
+# INGROUP: moko-platform.Universal
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
+# PATH: /templates/workflows/update-server.yml
+# VERSION: 05.00.00
+# BRIEF: Pre-release build + update server XML for dev/alpha/beta/rc branches
 #
-# Writes updates.xml with multiple <update> entries:
-#   - <tag>stable</tag>     on push to main (from auto-release)
-#   - <tag>rc</tag>         on push to rc/**
-#   - <tag>development</tag> on push to dev or dev/**
+# Thin wrapper around moko-platform CLI tools.
+# Builds packages, updates updates.xml, and optionally deploys via SFTP.
 #
-# Joomla filters by user's "Minimum Stability" setting.
+# Joomla filters update entries by the user's "Minimum Stability" setting.

-name: "Joomla: Update Server"
+name: "Update Server"

 on:
  push:
@@ -66,55 +64,60 @@ permissions:

 jobs:
  update-xml:
-    name: Update updates.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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@v4
        with:
-          token: ${{ secrets.GA_TOKEN }}
+          token: ${{ secrets.MOKOGITEA_TOKEN }}
          fetch-depth: 0

-      - name: Setup MokoStandards tools
+      - name: Setup moko-platform tools
        env:
-          MOKO_CLONE_TOKEN: ${{ secrets.GA_TOKEN }}
+          MOKO_CLONE_TOKEN: ${{ secrets.MOKOGITEA_TOKEN }}
          MOKO_CLONE_HOST: git.mokoconsulting.tech/MokoConsulting
-          COMPOSER_AUTH: '{"http-basic":{"git.mokoconsulting.tech":{"username":"token","password":"${{ secrets.GA_TOKEN }}"}}}'
+          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}/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
+            "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: Generate updates.xml entry
-        id: update
+      - 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 }}"
-          REPO="${{ github.repository }}"
-          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          VERSION=$(php /tmp/mokostandards-api/cli/version_read.php --path . 2>/dev/null || echo "0.0.0")

-          # Auto-bump patch on all branches (dev, alpha, beta, rc)
+          # Configure git for bot pushes
          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
          git config --local user.name "gitea-actions[bot]"
-          BUMPED=$(php /tmp/mokostandards-api/cli/version_bump.php --path . 2>/dev/null || true)
-          if [ -n "$BUMPED" ]; then
-            VERSION=$(php /tmp/mokostandards-api/cli/version_read.php --path . 2>/dev/null || echo "$VERSION")
-            git add -A
-            git commit -m "chore(version): auto-bump patch ${VERSION} [skip ci]" \
-              --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>" 2>/dev/null || true
-            git push 2>/dev/null || true
-          fi
+          git remote set-url origin "https://x-access-token:${{ secrets.MOKOGITEA_TOKEN }}@git.mokoconsulting.tech/${{ github.repository }}.git"

-          # Determine stability from branch or input
+          # Auto-bump patch version
+          php ${MOKO_CLI}/version_bump.php --path . 2>/dev/null || true
+
+          VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "0.0.0")
+
+          # Strip any existing suffix before applying stability
+          VERSION=$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
+
+          # Determine stability from branch or manual input
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            STABILITY="${{ inputs.stability }}"
          elif [[ "$BRANCH" == rc/* ]]; then
@@ -123,277 +126,122 @@ jobs:
            STABILITY="beta"
          elif [[ "$BRANCH" == alpha/* ]]; then
            STABILITY="alpha"
-          elif [[ "$BRANCH" == dev/* ]] || [[ "$BRANCH" == "dev" ]]; then
+          else
            STABILITY="development"
-          else
-            STABILITY="stable"
          fi

+          # Version suffix per stability stream
+          case "$STABILITY" in
+            development) SUFFIX="-dev";  TAG="development" ;;
+            alpha)       SUFFIX="-alpha"; TAG="alpha" ;;
+            beta)        SUFFIX="-beta";  TAG="beta" ;;
+            rc)          SUFFIX="-rc";    TAG="release-candidate" ;;
+            *)           SUFFIX="";       TAG="stable" ;;
+          esac
+
+          # Propagate version with stability suffix to all manifest files
+          php ${MOKO_CLI}/version_set_platform.php \
+            --path . --version "$VERSION" --branch "$BRANCH" --stability "$STABILITY" 2>/dev/null || true
+          php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
+
+          # Re-read version (now includes suffix from version_set_platform)
+          if [ -n "$SUFFIX" ]; then
+            VERSION="${VERSION}${SUFFIX}"
+          fi
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
          echo "stability=${STABILITY}" >> "$GITHUB_OUTPUT"
+          echo "suffix=${SUFFIX}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "display_version=${VERSION}" >> "$GITHUB_OUTPUT"

-          # Parse manifest (portable — no grep -P)
-          MANIFEST=$(find . -maxdepth 3 -name "*.xml" ! -path "./.git/*" ! -path "./build/*" -exec grep -l '<extension' {} \; 2>/dev/null | head -1)
-          if [ -z "$MANIFEST" ]; then
-            echo "No Joomla manifest found — skipping"
-            exit 0
-          fi
-
-          # Extract fields using sed (works on all runners)
-          EXT_NAME=$(sed -n 's/.*<name>\([^<]*\)<\/name>.*/\1/p' "$MANIFEST" | head -1)
-          EXT_TYPE=$(sed -n 's/.*<extension[^>]*type="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
-          EXT_ELEMENT=$(sed -n 's/.*<element>\([^<]*\)<\/element>.*/\1/p' "$MANIFEST" | head -1)
-          EXT_CLIENT=$(sed -n 's/.*<extension[^>]*client="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
-          EXT_FOLDER=$(sed -n 's/.*<extension[^>]*group="\([^"]*\)".*/\1/p' "$MANIFEST" | head -1)
-          EXT_VERSION=$(sed -n 's/.*<version>\([^<]*\)<\/version>.*/\1/p' "$MANIFEST" | head -1)
-          TARGET_PLATFORM=$(sed -n 's/.*\(<targetplatform[^/]*\/>\).*/\1/p' "$MANIFEST" | head -1)
-          PHP_MINIMUM=$(sed -n 's/.*<php_minimum>\([^<]*\)<\/php_minimum>.*/\1/p' "$MANIFEST" | head -1)
-
-          # Fallbacks
-          [ -z "$EXT_NAME" ] && EXT_NAME="${{ github.event.repository.name }}"
-          [ -z "$EXT_TYPE" ] && EXT_TYPE="component"
-
-          # Derive element if not in manifest: try XML filename, then repo name
-          if [ -z "$EXT_ELEMENT" ]; then
-            EXT_ELEMENT=$(basename "$MANIFEST" .xml | tr '[:upper:]' '[:lower:]')
-            case "$EXT_ELEMENT" in
-              templatedetails|manifest|*.xml) EXT_ELEMENT=$(echo "${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]' | tr -d ' -') ;;
-            esac
-          fi
-
-          # Use manifest version if README version is empty
-          [ "$VERSION" = "0.0.0" ] && [ -n "$EXT_VERSION" ] && VERSION="$EXT_VERSION"
-
-          [ -z "$TARGET_PLATFORM" ] && TARGET_PLATFORM=$(printf '<targetplatform name="joomla" version="((5.[0-9])|(6.[0-9]))" %s>' "/")
-
-          CLIENT_TAG=""
-          [ -n "$EXT_CLIENT" ] && CLIENT_TAG="<client>${EXT_CLIENT}</client>"
-          [ -z "$CLIENT_TAG" ] && ([ "$EXT_TYPE" = "module" ] || [ "$EXT_TYPE" = "plugin" ]) && CLIENT_TAG="<client>site</client>"
-
-          FOLDER_TAG=""
-          [ -n "$EXT_FOLDER" ] && [ "$EXT_TYPE" = "plugin" ] && FOLDER_TAG="<folder>${EXT_FOLDER}</folder>"
-
-          PHP_TAG=""
-          [ -n "$PHP_MINIMUM" ] && PHP_TAG="<php_minimum>${PHP_MINIMUM}</php_minimum>"
-
-          # Version suffix for non-stable
-          DISPLAY_VERSION="$VERSION"
-          case "$STABILITY" in
-            development) DISPLAY_VERSION="${VERSION}-dev" ;;
-            alpha)       DISPLAY_VERSION="${VERSION}-alpha" ;;
-            beta)        DISPLAY_VERSION="${VERSION}-beta" ;;
-            rc)          DISPLAY_VERSION="${VERSION}-rc" ;;
-          esac
-
-          MAJOR=$(echo "$VERSION" | awk -F. '{print $1}')
-
-          # Each stability level has its own release tag
-          case "$STABILITY" in
-            development) RELEASE_TAG="development" ;;
-            alpha)       RELEASE_TAG="alpha" ;;
-            beta)        RELEASE_TAG="beta" ;;
-            rc)          RELEASE_TAG="release-candidate" ;;
-            *)           RELEASE_TAG="v${MAJOR}" ;;
-          esac
-
-          PACKAGE_NAME="${EXT_ELEMENT}-${DISPLAY_VERSION}.zip"
-          DOWNLOAD_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}/releases/download/${RELEASE_TAG}/${PACKAGE_NAME}"
-          INFO_URL="${GITEA_URL}/${GITEA_ORG}/${GITEA_REPO}"
-
-          # -- Build install packages (ZIP + tar.gz) --------------------
-          SOURCE_DIR="src"
-          [ ! -d "$SOURCE_DIR" ] && SOURCE_DIR="htdocs"
-          if [ -d "$SOURCE_DIR" ]; then
-            EXCLUDES=".ftpignore sftp-config* *.ppk *.pem *.key .env*"
-            TAR_NAME="${EXT_ELEMENT}-${DISPLAY_VERSION}.tar.gz"
-
-            cd "$SOURCE_DIR"
-            zip -r "/tmp/${PACKAGE_NAME}" . -x $EXCLUDES
-            cd ..
-            tar -czf "/tmp/${TAR_NAME}" -C "$SOURCE_DIR" \
-              --exclude='.ftpignore' --exclude='sftp-config*' \
-              --exclude='*.ppk' --exclude='*.pem' --exclude='*.key' --exclude='.env*' .
-
-            SHA256=$(sha256sum "/tmp/${PACKAGE_NAME}" | cut -d' ' -f1)
-
-            # Ensure release exists on Gitea
-            RELEASE_JSON=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-              "${API_BASE}/releases/tags/${RELEASE_TAG}" 2>/dev/null || true)
-            RELEASE_ID=$(echo "$RELEASE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
-
-            if [ -z "$RELEASE_ID" ]; then
-              # Create release
-              RELEASE_JSON=$(curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-                -H "Content-Type: application/json" \
-                "${API_BASE}/releases" \
-                -d "$(python3 -c "import json; print(json.dumps({
-                  'tag_name': '${RELEASE_TAG}',
-                  'name': '${RELEASE_TAG} (${DISPLAY_VERSION})',
-                  'body': '${STABILITY} release',
-                  'prerelease': True,
-                  'target_commitish': 'main'
-                }))")" 2>/dev/null || true)
-              RELEASE_ID=$(echo "$RELEASE_JSON" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
-            fi
-
-            if [ -n "$RELEASE_ID" ]; then
-              # Delete existing assets with same name before uploading
-              ASSETS=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-                "${API_BASE}/releases/${RELEASE_ID}/assets" 2>/dev/null || echo "[]")
-              for ASSET_FILE in "$PACKAGE_NAME" "$TAR_NAME"; do
-                ASSET_ID=$(echo "$ASSETS" | python3 -c "
-          import sys,json
-          assets = json.load(sys.stdin)
-          for a in assets:
-              if a['name'] == '${ASSET_FILE}':
-                  print(a['id']); break
-          " 2>/dev/null || true)
-                if [ -n "$ASSET_ID" ]; then
-                  curl -sf -X DELETE -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-                    "${API_BASE}/releases/${RELEASE_ID}/assets/${ASSET_ID}" 2>/dev/null || true
-                fi
-              done
-
-              # Upload both formats
-              curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-                -H "Content-Type: application/octet-stream" \
-                --data-binary @"/tmp/${PACKAGE_NAME}" \
-                "${API_BASE}/releases/${RELEASE_ID}/assets?name=${PACKAGE_NAME}" > /dev/null 2>&1 || true
-
-              curl -sf -X POST -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
-                -H "Content-Type: application/octet-stream" \
-                --data-binary @"/tmp/${TAR_NAME}" \
-                "${API_BASE}/releases/${RELEASE_ID}/assets?name=${TAR_NAME}" > /dev/null 2>&1 || true
-            fi
-
-            echo "Packages: ${PACKAGE_NAME} + ${TAR_NAME} (SHA: ${SHA256})" >> $GITHUB_STEP_SUMMARY
-          else
-            SHA256=""
-          fi
-
-          # -- Build the new entry (canonical format matching release.yml) --
-          NEW_ENTRY=""
-          NEW_ENTRY="${NEW_ENTRY}  <update>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <name>${EXT_NAME}</name>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <description>${EXT_NAME} ${STABILITY} build.</description>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <element>${EXT_ELEMENT}</element>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <type>${EXT_TYPE}</type>\n"
-          [ -n "$CLIENT_TAG" ] && NEW_ENTRY="${NEW_ENTRY}    ${CLIENT_TAG}\n"
-          [ -n "$FOLDER_TAG" ] && NEW_ENTRY="${NEW_ENTRY}    ${FOLDER_TAG}\n"
-          NEW_ENTRY="${NEW_ENTRY}    <version>${VERSION}</version>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <creationDate>$(date +%Y-%m-%d)</creationDate>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <infourl title='${EXT_NAME}'>https://git.mokoconsulting.tech/${GITEA_ORG}/${GITEA_REPO}/releases/tag/${RELEASE_TAG}</infourl>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <downloads>\n"
-          NEW_ENTRY="${NEW_ENTRY}      <downloadurl type='full' format='zip'>${DOWNLOAD_URL}</downloadurl>\n"
-          NEW_ENTRY="${NEW_ENTRY}    </downloads>\n"
-          [ -n "$SHA256" ] && NEW_ENTRY="${NEW_ENTRY}    <sha256>${SHA256}</sha256>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <tags><tag>${STABILITY}</tag></tags>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <maintainer>Moko Consulting</maintainer>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <maintainerurl>https://mokoconsulting.tech</maintainerurl>\n"
-          NEW_ENTRY="${NEW_ENTRY}    <targetplatform name='joomla' version='(5|6).*'/>\n"
-          [ -n "$PHP_MINIMUM" ] && NEW_ENTRY="${NEW_ENTRY}    <php_minimum>${PHP_MINIMUM}</php_minimum>\n"
-          NEW_ENTRY="${NEW_ENTRY}  </update>"
-
-          # -- Write new entry to temp file --------------------------------
-          printf '%b' "$NEW_ENTRY" > /tmp/new_entry.xml
-
-          # -- Merge into updates.xml ----------------------------------------
-          # Cascade: stable→all | rc→rc+lower | beta→beta+lower | alpha→alpha+dev | dev→dev
-          CASCADE_MAP="stable:development,alpha,beta,rc,stable rc:development,alpha,beta,rc beta:development,alpha,beta alpha:development,alpha development:development"
-          TARGETS=""
-          for entry in $CASCADE_MAP; do
-            key="${entry%%:*}"
-            vals="${entry#*:}"
-            if [ "$key" = "${STABILITY}" ]; then
-              TARGETS="$vals"
-              break
-            fi
-          done
-          [ -z "$TARGETS" ] && TARGETS="${STABILITY}"
-
-          echo "Cascade: ${STABILITY} → ${TARGETS}"
-
-          # Create updates.xml if missing
-          if [ ! -f "updates.xml" ]; then
-            printf '%s\n' "<?xml version='1.0' encoding='UTF-8'?>" > updates.xml
-            printf '%s\n' "<!-- Copyright (C) $(date +%Y) Moko Consulting -->" >> updates.xml
-            printf '%s\n' "<updates>" >> updates.xml
-            printf '%s\n' "</updates>" >> updates.xml
-          fi
-
-          # Update existing blocks or create missing ones
-          export PY_TARGETS="$TARGETS" PY_VERSION="$VERSION" PY_DATE="$(date +%Y-%m-%d)"
-          python3 << 'PYEOF'
-          import re, os
-
-          targets = os.environ["PY_TARGETS"].split(",")
-          version = os.environ["PY_VERSION"]
-          date = os.environ["PY_DATE"]
-
-          with open("updates.xml") as f:
-              content = f.read()
-          with open("/tmp/new_entry.xml") as f:
-              new_entry_template = f.read()
-
-          for tag in targets:
-              tag = tag.strip()
-              # Build entry with this tag's name
-              new_entry = re.sub(r"<tag>[^<]*</tag>", f"<tag>{tag}</tag>", new_entry_template)
-
-              # Try to find existing block (handles both single-line and multi-line <tags>)
-              block_pattern = r"(<update>(?:(?!</update>).)*?<tag>" + re.escape(tag) + r"</tag>.*?</update>)"
-              match = re.search(block_pattern, content, re.DOTALL)
-
-              if match:
-                  # Update in place — replace entire block
-                  content = content.replace(match.group(1), new_entry.strip())
-                  print(f"  UPDATED: <tag>{tag}</tag> → {version}")
-              else:
-                  # Create — insert before </updates>
-                  content = content.replace("</updates>", "\n" + new_entry.strip() + "\n\n</updates>")
-                  print(f"  CREATED: <tag>{tag}</tag> → {version}")
-
-          # Clean up excessive blank lines
-          content = re.sub(r"\n{3,}", "\n\n", content)
-
-          with open("updates.xml", "w") as f:
-              f.write(content)
-          PYEOF
-
-          # Commit
-          git config --local user.email "gitea-actions[bot]@mokoconsulting.tech"
-          git config --local user.name "gitea-actions[bot]"
-          git add updates.xml
+          # Commit version bump if changed
+          git add -A
          git diff --cached --quiet || {
-            git commit -m "chore: update updates.xml (${STABILITY}: ${DISPLAY_VERSION}) [skip ci]" \
+            git commit -m "chore(version): auto-bump ${VERSION} [skip ci]" \
              --author="gitea-actions[bot] <gitea-actions[bot]@mokoconsulting.tech>"
            git push
          }

-      # -- Sync updates.xml to main (for non-main branches) ----------------------
+      - 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'
+        if: github.ref_name != 'main' && steps.platform.outputs.platform == 'joomla'
        run: |
          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"
-          GA_TOKEN="${{ secrets.GA_TOKEN }}"
+          GITEA_TOKEN="${{ secrets.MOKOGITEA_TOKEN }}"

-          FILE_SHA=$(curl -sf -H "Authorization: token ${GA_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
-            CONTENT=$(base64 -w0 updates.xml)
-            curl -sf -X PUT -H "Authorization: token ${GA_TOKEN}" \
-              -H "Content-Type: application/json" \
-              "${API_BASE}/contents/updates.xml" \
-              -d "$(python3 -c "import json; print(json.dumps({
-                'content': '${CONTENT}',
-                'sha': '${FILE_SHA}',
-                'message': 'chore: sync updates.xml from ${STABILITY} [skip ci]',
-                'branch': 'main'
-              }))")" > /dev/null 2>&1 \
-              && echo "updates.xml synced to main (${STABILITY})" >> $GITHUB_STEP_SUMMARY \
-              || echo "WARNING: failed to sync updates.xml to main" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "WARNING: could not get updates.xml SHA from main" >> $GITHUB_STEP_SUMMARY
+            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
@@ -407,12 +255,11 @@ jobs:
          DEV_KEY: ${{ secrets.DEV_FTP_KEY }}
          DEV_PASS: ${{ secrets.DEV_FTP_PASSWORD }}
        run: |
-          # -- Permission check: admin or maintain role required --------
+          # Permission check: admin or maintain role required
          ACTOR="${{ github.actor }}"
-          REPO="${{ github.repository }}"
          API_BASE="${GITEA_URL}/api/v1/repos/${GITEA_ORG}/${GITEA_REPO}"

-          PERMISSION=$(curl -sf -H "Authorization: token ${{ secrets.GA_TOKEN }}" \
+          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
@@ -442,11 +289,11 @@ jobs:
            printf ',"password":"%s"}' "$DEV_PASS" >> /tmp/sftp-config.json
          fi

-          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 --path . --src-dir "$SOURCE_DIR" --config /tmp/sftp-config.json
-          elif [ -f "/tmp/mokostandards-api/deploy/deploy-sftp.php" ]; then
-            php /tmp/mokostandards-api/deploy/deploy-sftp.php --path . --src-dir "$SOURCE_DIR" --config /tmp/sftp-config.json
+          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
@@ -454,11 +301,12 @@ jobs:
      - name: Summary
        if: always()
        run: |
-          echo "## Joomla Update Server" >> $GITHUB_STEP_SUMMARY
+          VERSION="${{ steps.meta.outputs.version }}"
+          STABILITY="${{ steps.meta.outputs.stability }}"
+          DISPLAY="${{ steps.meta.outputs.display_version }}"
+          echo "## Update Server" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
          echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
          echo "| Stability | \`${STABILITY}\` |" >> $GITHUB_STEP_SUMMARY
-          echo "| Version | \`${DISPLAY_VERSION}\` |" >> $GITHUB_STEP_SUMMARY
-          echo "| Element | \`${EXT_ELEMENT}\` |" >> $GITHUB_STEP_SUMMARY
-          echo "| Download | [ZIP](${DOWNLOAD_URL}) |" >> $GITHUB_STEP_SUMMARY
+          echo "| Version | \`${DISPLAY}\` |" >> $GITHUB_STEP_SUMMARY
@@ -1,21 +1,44 @@
 # Changelog

-<!-- VERSION: 01.00.00 -->
+<!-- VERSION: 01.00.01 -->

-All notable changes to MokoOpenGraph will be documented in this file.
+All notable changes to MokoJoomOpenGraph will be documented in this file.

 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

 ## [Unreleased]

+### Security
+- Fix JSON-LD XSS vulnerability via `</script>` injection in content data (#34)
+- Add ACL permission checks to Batch and ImportExport controllers (#37)
+- Add CSV import file type, MIME type, size, and content_type validation (#35)
+- Fix multilingual data corruption in content plugin load/save (#41)
+
 ### Added
- Initial package structure with component, system plugin, and content plugin
- Open Graph meta tag injection via system plugin (`onBeforeCompileHead`)
- Twitter/X Card meta tag support (Summary and Summary with Large Image)
- Per-article OG fields in the article editor
- Per-menu-item OG fields in the menu item editor
- Auto-generation of OG tags from article title, description, and images
+- Site-wide default OG title and description plugin parameters
+- Discord embed color via `theme-color` meta tag (color picker in plugin config)
+- LinkedIn article tags: `article:published_time`, `article:modified_time`, `article:author`
+- `og:image:width` and `og:image:height` for faster social preview rendering
+- `onMokoOGAfterRender` event for third-party plugin extensibility
+- Joomla Web Services API for OG tags — full CRUD at `/api/v1/mokoog/tags` (#27)
+- Live social preview in article/menu editors (Facebook and Twitter/X card mockups) (#3)
+- CSV import/export for bulk OG tag management (#12)
+- OG image text overlay generator (#7)
+- Multilingual OG tag support with per-language records (#11)
+- JSON-LD structured data: Article, WebPage, BreadcrumbList schemas (#6)
+- Social platform debugger quick links (Facebook, LinkedIn, Google) (#9)
+- Content type adapter architecture for K2, VirtueMart, HikaShop (#5)
+- WhatsApp and Telegram link preview optimization (#10)
+- Category-level OG tag support (#4)
+- Batch OG tag generation for existing articles (#1)
+- Auto-resize OG images to 1200x630px with center crop (#2)
+- SEO meta tag management: title, description, robots, canonical URL (#8)
+- Per-article and per-menu-item OG fields in the editor
+- Auto-generation of OG tags from article content, title, and images
 - Default fallback image configuration
- Admin tag manager component for viewing all OG records
- Facebook App ID support
- Database table `#__mokoog_tags` for storing custom OG data
+- Admin tag manager component with filtering, search, and pagination
+- Facebook App ID and Telegram channel support
+- Database table `#__mokoog_tags` with multilingual unique key
+
+### Removed
+- Removed deploy-manual.yml workflow — using Joomla update server for distribution
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code when working with this repository.

 ## Project Overview

-**MokoOpenGraph** -- Open Graph, Twitter Card, and social sharing meta tag management for Joomla
+**MokoJoomOpenGraph** -- Open Graph, Twitter Card, and social sharing meta tag management for Joomla

 | Field | Value |
 |---|---|
@@ -12,7 +12,7 @@ This file provides guidance to Claude Code when working with this repository.
 | **Language** | PHP |
 | **Default branch** | main |
 | **License** | GPL-3.0-or-later |
-| **Wiki** | [MokoOpenGraph Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoOpenGraph/wiki) |
+| **Wiki** | [MokoJoomOpenGraph Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/wiki) |
 | **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) |

 ## Common Commands
@@ -0,0 +1,28 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at hello@mokoconsulting.tech. All complaints will be reviewed and investigated.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
@@ -0,0 +1,34 @@
+# Contributing to MokoJoomOpenGraph
+
+Thank you for your interest in contributing to MokoJoomOpenGraph.
+
+## Getting Started
+
+1. Fork the repository on Gitea
+2. Create a feature branch from `dev` (`feature/your-feature`)
+3. Make your changes following the coding standards below
+4. Submit a pull request targeting `dev`
+
+## Branch Strategy
+
+- `main` — stable releases only
+- `dev` — active development
+- `feature/*` — new features (target `dev`)
+- `fix/*` — bug fixes (target `dev`)
+- `hotfix/*` — urgent fixes (target `dev` or `main`)
+
+## Coding Standards
+
+- PHP 8.1+ required
+- Follow Joomla coding standards
+- SPDX license headers on all PHP files
+- Use `SubscriberInterface` for event subscription
+- Use `bind() -> check() -> store()` for Table operations
+
+## Reporting Issues
+
+Report bugs and feature requests via [Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/issues).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under GPL-3.0-or-later.
@@ -2,7 +2,7 @@
 # Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 # SPDX-License-Identifier: GPL-3.0-or-later
 #
-# MokoOpenGraph — Open Graph & social sharing meta tag management
+# MokoJoomOpenGraph — Open Graph & social sharing meta tag management

 # ==============================================================================
 # CONFIGURATION - Customize these for your extension
@@ -1,40 +1,69 @@
-# MokoOpenGraph
+# MokoJoomOpenGraph

-<!-- VERSION: 01.00.00 -->
+<!-- VERSION: 01.00.01 -->

 Open Graph, Twitter Card, and social sharing meta tag management for Joomla 4/5/6.

 ## Overview

-MokoOpenGraph gives you full control over how your Joomla content appears when shared on Facebook, Twitter/X, LinkedIn, WhatsApp, and other social platforms. Set custom titles, descriptions, and images per article and menu item — or let the extension auto-generate them from your existing content.
+MokoJoomOpenGraph gives you full control over how your Joomla content appears when shared on Facebook, Twitter/X, LinkedIn, Discord, WhatsApp, Telegram, and other social platforms. Set custom titles, descriptions, and images per article, menu item, and category — or let the extension auto-generate them from your existing content.

 ## Features

- **Open Graph tags** — `og:title`, `og:description`, `og:image`, `og:url`, `og:type`, `og:site_name`
+### Social Meta Tags
+- **Open Graph tags** — `og:title`, `og:description`, `og:image`, `og:url`, `og:type`, `og:site_name`, `og:locale`
 - **Twitter/X Cards** — Summary and Summary with Large Image card types
- **Per-article control** — Custom OG fields in the article editor
+- **LinkedIn** — `article:published_time`, `article:modified_time`, `article:author`
+- **Discord** — Custom embed color via `theme-color` meta tag
+- **Telegram** — `telegram:channel` for link previews
+- **Facebook** — `fb:app_id` support, `og:image:width`/`og:image:height` for instant previews
+
+### Content Management
+- **Per-article control** — Custom OG fields tab in the article editor
 - **Per-menu-item control** — Custom OG fields in the menu item editor
- **Auto-generation** — Automatically builds tags from article content, title, and images
- **Default fallback image** — Site-wide default when no article image exists
- **Admin tag manager** — View and manage all OG records from a central dashboard
- **Facebook App ID** — Optional `fb:app_id` meta tag support
- **Joomla 4/5/6** — Modern DI container architecture, Joomla coding standards
+- **Per-category control** — Category-level OG tag overrides
+- **Multilingual support** — Per-language OG data with language-aware fallback
+- **Auto-generation** — Builds tags from article content, title, and images automatically
+- **Site-wide defaults** — Default OG title, description, and image for all pages
+
+### SEO
+- **SEO title override** — Custom `<title>` tag per page
+- **Meta description** — Per-page meta description control
+- **Robots directive** — Per-page noindex/nofollow settings
+- **Canonical URL** — Custom canonical URL overrides
+- **JSON-LD structured data** — Article, WebPage, BreadcrumbList, Organization schemas
+
+### Admin Tools
+- **Tag manager dashboard** — View and manage all OG records centrally
+- **Batch generation** — Auto-generate OG tags for all existing articles
+- **CSV import/export** — Bulk manage OG data via CSV files
+- **SEO health badges** — Visual indicators for missing descriptions, long titles, noindex
+- **Debug links** — Quick links to Facebook Debugger, LinkedIn Inspector, Google Rich Results
+- **Live preview** — Real-time Facebook and Twitter/X card preview in the editor
+
+### Developer Features
+- **REST API** — Full CRUD via Joomla Web Services (`/api/v1/mokoog/tags`)
+- **Content type adapters** — Extensible architecture for K2, VirtueMart, HikaShop
+- **Plugin event** — `onMokoOGAfterRender` for third-party plugins to add custom social tags
+- **OG image generator** — Text overlay on template backgrounds with auto-resize to 1200x630

 ## Installation

-1. Download the latest `pkg_mokoog-*.zip` from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoOpenGraph/releases)
+1. Download the latest `pkg_mokoog-*.zip` from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/releases)
 2. In Joomla Administrator → Extensions → Install → Upload Package File
-3. The system plugin is enabled automatically on install
+3. All plugins are enabled automatically on install

 ## Configuration

-Navigate to **Extensions → Plugins → System - MokoOpenGraph** to configure:
+Navigate to **Extensions → Plugins → System - MokoJoomOpenGraph** to configure:
 - Site name override
+- Default OG title and description (site-wide fallback)
 - Default fallback image
 - Twitter Card type and @username
 - Facebook App ID
- Auto-generation behavior
- Description length limit
+- Discord embed color
+- Telegram channel
+- Auto-generation, image resize, JSON-LD, and description length settings

 ## License

@@ -1,7 +1,7 @@
-; MokoOpenGraph - Package System Language File
+; MokoJoomOpenGraph - Package System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-PKG_MOKOOG="MokoOpenGraph"
+PKG_MOKOOG="MokoJoomOpenGraph"
 PKG_MOKOOG_DESCRIPTION="Complete Open Graph, Twitter Card, and social sharing meta tag management for Joomla. Control how every page appears when shared on Facebook, Twitter/X, LinkedIn, WhatsApp, and more."
-PKG_MOKOOG_PHP_VERSION_ERROR="MokoOpenGraph requires PHP %s or later."
+PKG_MOKOOG_PHP_VERSION_ERROR="MokoJoomOpenGraph requires PHP %s or later."
@@ -1,7 +1,7 @@
-; MokoOpenGraph - Package System Language File
+; MokoJoomOpenGraph - Package System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-PKG_MOKOOG="MokoOpenGraph"
+PKG_MOKOOG="MokoJoomOpenGraph"
 PKG_MOKOOG_DESCRIPTION="Complete Open Graph, Twitter Card, and social sharing meta tag management for Joomla. Control how every page appears when shared on Facebook, Twitter/X, LinkedIn, WhatsApp, and more."
-PKG_MOKOOG_PHP_VERSION_ERROR="MokoOpenGraph requires PHP %s or later."
+PKG_MOKOOG_PHP_VERSION_ERROR="MokoJoomOpenGraph requires PHP %s or later."
@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog.api
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Api\Controller;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\CMS\MVC\Controller\ApiController;
+
+class TagsController extends ApiController
+{
+    /**
+     * The content type for JSON:API output.
+     *
+     * @var string
+     */
+    protected $contentType = 'tags';
+
+    /**
+     * The default view for the API.
+     *
+     * @var string
+     */
+    protected $default_view = 'tags';
+
+    /**
+     * Lookup an OG tag by content_type and content_id.
+     *
+     * GET /api/index.php/v1/mokoog/lookup/:content_type/:content_id
+     *
+     * @return  static
+     */
+    public function lookup(): static
+    {
+        $contentType = $this->input->getString('content_type', '');
+        $contentId   = $this->input->getInt('content_id', 0);
+
+        if (empty($contentType) || $contentId <= 0) {
+            throw new \RuntimeException('content_type and content_id are required', 400);
+        }
+
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('id'))
+            ->from($db->quoteName('#__mokoog_tags'))
+            ->where($db->quoteName('content_type') . ' = ' . $db->quote($contentType))
+            ->where($db->quoteName('content_id') . ' = ' . $contentId);
+
+        $db->setQuery($query);
+        $id = $db->loadResult();
+
+        if (!$id) {
+            throw new \RuntimeException('OG tag not found for ' . $contentType . ':' . $contentId, 404);
+        }
+
+        $this->input->set('id', $id);
+
+        return $this->displayItem();
+    }
+}
@@ -0,0 +1,66 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog.api
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Api\View\Tags;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\MVC\View\JsonApiView as BaseApiView;
+
+class JsonapiView extends BaseApiView
+{
+    /**
+     * The fields to render in the API response.
+     *
+     * Whitelist of fields from #__mokoog_tags that are safe to expose.
+     *
+     * @var array
+     */
+    protected $fieldsToRenderItem = [
+        'id',
+        'content_type',
+        'content_id',
+        'og_title',
+        'og_description',
+        'og_image',
+        'og_type',
+        'seo_title',
+        'meta_description',
+        'robots',
+        'canonical_url',
+        'language',
+        'published',
+        'created',
+        'modified',
+    ];
+
+    /**
+     * The fields to render in list responses.
+     *
+     * @var array
+     */
+    protected $fieldsToRenderList = [
+        'id',
+        'content_type',
+        'content_id',
+        'og_title',
+        'og_description',
+        'og_image',
+        'og_type',
+        'seo_title',
+        'meta_description',
+        'robots',
+        'canonical_url',
+        'language',
+        'published',
+        'created',
+        'modified',
+    ];
+}
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -70,4 +70,37 @@
            <option value="0">JUNPUBLISHED</option>
        </field>
    </fieldset>
+    <fieldset name="seo" label="SEO Meta Tags">
+        <field
+            name="seo_title"
+            type="text"
+            label="PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE"
+            description="PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE_DESC"
+            filter="string"
+            maxlength="70"
+        />
+        <field
+            name="meta_description"
+            type="textarea"
+            label="PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION"
+            description="PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION_DESC"
+            filter="string"
+            rows="3"
+            maxlength="200"
+        />
+        <field
+            name="robots"
+            type="text"
+            label="PLG_CONTENT_MOKOOG_FIELD_ROBOTS"
+            description="PLG_CONTENT_MOKOOG_FIELD_ROBOTS_DESC"
+            filter="string"
+        />
+        <field
+            name="canonical_url"
+            type="url"
+            label="PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL"
+            description="PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL_DESC"
+            filter="url"
+        />
+    </fieldset>
 </form>
@@ -1,9 +1,9 @@
-; MokoOpenGraph - Component Language File
+; MokoJoomOpenGraph - Component Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-COM_MOKOOG="MokoOpenGraph"
-COM_MOKOOG_TAGS_TITLE="MokoOpenGraph - Tag Manager"
+COM_MOKOOG="MokoJoomOpenGraph"
+COM_MOKOOG_TAGS_TITLE="MokoJoomOpenGraph - Tag Manager"
 COM_MOKOOG_SUBMENU_TAGS="Tags"
 COM_MOKOOG_NO_TAGS="No Open Graph tags have been created yet. Tags are created automatically when you edit articles or menu items."
 COM_MOKOOG_TABLE_CAPTION="Table of Open Graph tags"
@@ -13,4 +13,47 @@ COM_MOKOOG_HEADING_CONTENT_TYPE="Content Type"
 COM_MOKOOG_HEADING_CONTENT_ID="Content ID"
 COM_MOKOOG_HEADING_OG_TITLE="OG Title"
 COM_MOKOOG_HEADING_IMAGE="Image"
+COM_MOKOOG_HEADING_SEO="SEO"
+COM_MOKOOG_HEADING_DEBUG="Debug"
 COM_MOKOOG_HEADING_MODIFIED="Modified"
+
+COM_MOKOOG_SEO_OK="OK"
+COM_MOKOOG_SEO_MISSING_DESC="No meta description"
+COM_MOKOOG_SEO_TITLE_LONG="SEO title too long"
+COM_MOKOOG_SEO_NOINDEX="noindex"
+
+COM_MOKOOG_FIELD_CONTENT_TYPE="Content Type"
+COM_MOKOOG_FIELD_CONTENT_ID="Content ID"
+COM_MOKOOG_FIELD_OG_TITLE="OG Title"
+COM_MOKOOG_FIELD_OG_TITLE_DESC="Custom title for social sharing."
+COM_MOKOOG_FIELD_OG_DESCRIPTION="OG Description"
+COM_MOKOOG_FIELD_OG_DESCRIPTION_DESC="Custom description for social sharing."
+COM_MOKOOG_FIELD_OG_IMAGE="OG Image"
+COM_MOKOOG_FIELD_OG_IMAGE_DESC="Custom image for social sharing."
+COM_MOKOOG_FIELD_OG_TYPE="OG Type"
+COM_MOKOOG_FIELD_OG_TYPE_DESC="The Open Graph content type."
+
+COM_MOKOOG_FILTER_SEARCH="Search OG titles"
+COM_MOKOOG_FILTER_CONTENT_TYPE="Content Type"
+COM_MOKOOG_FILTER_SELECT_TYPE="- Select Type -"
+COM_MOKOOG_HEADING_OG_TITLE_ASC="OG Title ascending"
+COM_MOKOOG_HEADING_OG_TITLE_DESC="OG Title descending"
+COM_MOKOOG_HEADING_MODIFIED_ASC="Modified ascending"
+COM_MOKOOG_HEADING_MODIFIED_DESC="Modified descending"
+
+COM_MOKOOG_TOOLBAR_BATCH_GENERATE="Batch Generate"
+COM_MOKOOG_BATCH_TITLE="Batch OG Tag Generation"
+COM_MOKOOG_BATCH_COUNTING="Counting articles without OG tags..."
+COM_MOKOOG_BATCH_NONE="All articles already have OG tags."
+COM_MOKOOG_BATCH_FOUND="articles found without OG tags."
+COM_MOKOOG_BATCH_PROCESSED="processed"
+COM_MOKOOG_BATCH_COMPLETE="Batch generation complete!"
+COM_MOKOOG_BATCH_ERROR="Error:"
+
+COM_MOKOOG_TOOLBAR_EXPORT="Export CSV"
+COM_MOKOOG_TOOLBAR_IMPORT="Import CSV"
+COM_MOKOOG_IMPORT_NO_FILE="No CSV file was uploaded."
+COM_MOKOOG_IMPORT_INVALID_TYPE="Invalid file type. Please upload a .csv file."
+COM_MOKOOG_IMPORT_FILE_TOO_LARGE="File is too large. Maximum allowed size is %s."
+COM_MOKOOG_IMPORT_READ_ERROR="Could not read the uploaded CSV file."
+COM_MOKOOG_IMPORT_RESULT="Import complete: %d created, %d updated, %d skipped."
@@ -1,6 +1,6 @@
-; MokoOpenGraph - Component System Language File
+; MokoJoomOpenGraph - Component System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-COM_MOKOOG="MokoOpenGraph"
+COM_MOKOOG="MokoJoomOpenGraph"
 COM_MOKOOG_DESCRIPTION="Manage Open Graph and social sharing tags for all your content. View, edit, and batch-process OG metadata."
@@ -1,9 +1,9 @@
-; MokoOpenGraph - Component Language File
+; MokoJoomOpenGraph - Component Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-COM_MOKOOG="MokoOpenGraph"
-COM_MOKOOG_TAGS_TITLE="MokoOpenGraph - Tag Manager"
+COM_MOKOOG="MokoJoomOpenGraph"
+COM_MOKOOG_TAGS_TITLE="MokoJoomOpenGraph - Tag Manager"
 COM_MOKOOG_SUBMENU_TAGS="Tags"
 COM_MOKOOG_NO_TAGS="No Open Graph tags have been created yet. Tags are created automatically when you edit articles or menu items."
 COM_MOKOOG_TABLE_CAPTION="Table of Open Graph tags"
@@ -13,4 +13,47 @@ COM_MOKOOG_HEADING_CONTENT_TYPE="Content Type"
 COM_MOKOOG_HEADING_CONTENT_ID="Content ID"
 COM_MOKOOG_HEADING_OG_TITLE="OG Title"
 COM_MOKOOG_HEADING_IMAGE="Image"
+COM_MOKOOG_HEADING_SEO="SEO"
+COM_MOKOOG_HEADING_DEBUG="Debug"
 COM_MOKOOG_HEADING_MODIFIED="Modified"
+
+COM_MOKOOG_SEO_OK="OK"
+COM_MOKOOG_SEO_MISSING_DESC="No meta description"
+COM_MOKOOG_SEO_TITLE_LONG="SEO title too long"
+COM_MOKOOG_SEO_NOINDEX="noindex"
+
+COM_MOKOOG_FIELD_CONTENT_TYPE="Content Type"
+COM_MOKOOG_FIELD_CONTENT_ID="Content ID"
+COM_MOKOOG_FIELD_OG_TITLE="OG Title"
+COM_MOKOOG_FIELD_OG_TITLE_DESC="Custom title for social sharing."
+COM_MOKOOG_FIELD_OG_DESCRIPTION="OG Description"
+COM_MOKOOG_FIELD_OG_DESCRIPTION_DESC="Custom description for social sharing."
+COM_MOKOOG_FIELD_OG_IMAGE="OG Image"
+COM_MOKOOG_FIELD_OG_IMAGE_DESC="Custom image for social sharing."
+COM_MOKOOG_FIELD_OG_TYPE="OG Type"
+COM_MOKOOG_FIELD_OG_TYPE_DESC="The Open Graph content type."
+
+COM_MOKOOG_FILTER_SEARCH="Search OG titles"
+COM_MOKOOG_FILTER_CONTENT_TYPE="Content Type"
+COM_MOKOOG_FILTER_SELECT_TYPE="- Select Type -"
+COM_MOKOOG_HEADING_OG_TITLE_ASC="OG Title ascending"
+COM_MOKOOG_HEADING_OG_TITLE_DESC="OG Title descending"
+COM_MOKOOG_HEADING_MODIFIED_ASC="Modified ascending"
+COM_MOKOOG_HEADING_MODIFIED_DESC="Modified descending"
+
+COM_MOKOOG_TOOLBAR_BATCH_GENERATE="Batch Generate"
+COM_MOKOOG_BATCH_TITLE="Batch OG Tag Generation"
+COM_MOKOOG_BATCH_COUNTING="Counting articles without OG tags..."
+COM_MOKOOG_BATCH_NONE="All articles already have OG tags."
+COM_MOKOOG_BATCH_FOUND="articles found without OG tags."
+COM_MOKOOG_BATCH_PROCESSED="processed"
+COM_MOKOOG_BATCH_COMPLETE="Batch generation complete!"
+COM_MOKOOG_BATCH_ERROR="Error:"
+
+COM_MOKOOG_TOOLBAR_EXPORT="Export CSV"
+COM_MOKOOG_TOOLBAR_IMPORT="Import CSV"
+COM_MOKOOG_IMPORT_NO_FILE="No CSV file was uploaded."
+COM_MOKOOG_IMPORT_INVALID_TYPE="Invalid file type. Please upload a .csv file."
+COM_MOKOOG_IMPORT_FILE_TOO_LARGE="File is too large. Maximum allowed size is %s."
+COM_MOKOOG_IMPORT_READ_ERROR="Could not read the uploaded CSV file."
+COM_MOKOOG_IMPORT_RESULT="Import complete: %d created, %d updated, %d skipped."
@@ -1,6 +1,6 @@
-; MokoOpenGraph - Component System Language File
+; MokoJoomOpenGraph - Component System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-COM_MOKOOG="MokoOpenGraph"
+COM_MOKOOG="MokoJoomOpenGraph"
 COM_MOKOOG_DESCRIPTION="Manage Open Graph and social sharing tags for all your content. View, edit, and batch-process OG metadata."
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -8,7 +8,7 @@
 -->
 <extension type="component" method="upgrade">
    <name>com_mokoog</name>
-    <version>01.00.00</version>
+    <version>01.00.01-rc</version>
    <creationDate>2026-05-23</creationDate>
    <author>Moko Consulting</author>
    <authorEmail>hello@mokoconsulting.tech</authorEmail>
@@ -42,6 +42,7 @@
            <filename>provider.php</filename>
        </files>
        <files folder="src">
+            <folder>ContentType</folder>
            <folder>Controller</folder>
            <folder>Extension</folder>
            <folder>Model</folder>
@@ -68,4 +69,10 @@
            <menu link="option=com_mokoog&amp;view=tags">COM_MOKOOG_SUBMENU_TAGS</menu>
        </submenu>
    </administration>
+
+    <api>
+        <files folder="api">
+            <folder>src</folder>
+        </files>
+    </api>
 </extension>
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -23,7 +23,7 @@ class Com_MokoOGInstallerScript
     */
    public function install(InstallerAdapter $parent): void
    {
-        echo '<p>MokoOpenGraph component installed successfully.</p>';
+        echo '<p>MokoJoomOpenGraph component installed successfully.</p>';
    }

    /**
@@ -35,6 +35,6 @@ class Com_MokoOGInstallerScript
     */
    public function update(InstallerAdapter $parent): void
    {
-        echo '<p>MokoOpenGraph component updated successfully.</p>';
+        echo '<p>MokoJoomOpenGraph component updated successfully.</p>';
    }
 }
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,5 +1,5 @@
 --
-- MokoOpenGraph - Database Schema
+-- MokoJoomOpenGraph - Database Schema
 -- Copyright (C) 2026 Moko Consulting. All rights reserved.
 -- License: GPL-3.0-or-later
 --
@@ -12,10 +12,15 @@ CREATE TABLE IF NOT EXISTS `#__mokoog_tags` (
    `og_description` TEXT NOT NULL,
    `og_image`       VARCHAR(512) NOT NULL DEFAULT '',
    `og_type`        VARCHAR(50) NOT NULL DEFAULT 'article',
+    `seo_title`      VARCHAR(70) NOT NULL DEFAULT '',
+    `meta_description` VARCHAR(200) NOT NULL DEFAULT '',
+    `robots`         VARCHAR(100) NOT NULL DEFAULT '',
+    `canonical_url`  VARCHAR(512) NOT NULL DEFAULT '',
+    `language`       CHAR(7) NOT NULL DEFAULT '*',
    `published`      TINYINT(1) NOT NULL DEFAULT 1,
    `created`        DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
    `modified`       DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
    PRIMARY KEY (`id`),
-    UNIQUE KEY `idx_content` (`content_type`, `content_id`),
+    UNIQUE KEY `idx_content_lang` (`content_type`, `content_id`, `language`),
    KEY `idx_published` (`published`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
@@ -1,5 +1,5 @@
 --
-- MokoOpenGraph - Uninstall
+-- MokoJoomOpenGraph - Uninstall
 --

 DROP TABLE IF EXISTS `#__mokoog_tags`;
@@ -0,0 +1,9 @@
+--
+-- MokoJoomOpenGraph 01.01.00 — Add SEO meta management columns
+--
+
+ALTER TABLE `#__mokoog_tags`
+    ADD COLUMN `seo_title` VARCHAR(70) NOT NULL DEFAULT '' AFTER `og_type`,
+    ADD COLUMN `meta_description` VARCHAR(200) NOT NULL DEFAULT '' AFTER `seo_title`,
+    ADD COLUMN `robots` VARCHAR(100) NOT NULL DEFAULT '' AFTER `meta_description`,
+    ADD COLUMN `canonical_url` VARCHAR(512) NOT NULL DEFAULT '' AFTER `robots`;
@@ -0,0 +1,10 @@
+--
+-- MokoJoomOpenGraph 01.02.00 — Add multilingual OG tag support
+--
+
+ALTER TABLE `#__mokoog_tags`
+    ADD COLUMN `language` CHAR(7) NOT NULL DEFAULT '*' AFTER `canonical_url`;
+
+ALTER TABLE `#__mokoog_tags`
+    DROP INDEX `idx_content`,
+    ADD UNIQUE KEY `idx_content_lang` (`content_type`, `content_id`, `language`);
@@ -0,0 +1,60 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\ContentType;
+
+defined('_JEXEC') or die;
+
+interface ContentTypeInterface
+{
+    /**
+     * Check if this adapter can handle the given component/view.
+     *
+     * @param   string  $option  Component option (e.g. com_virtuemart)
+     * @param   string  $view    View name (e.g. productdetails)
+     *
+     * @return  bool
+     */
+    public function canHandle(string $option, string $view): bool;
+
+    /**
+     * Get the content type identifier for database storage.
+     *
+     * @return  string
+     */
+    public function getContentType(): string;
+
+    /**
+     * Get the title for the content item.
+     *
+     * @param   int  $id  Content item ID
+     *
+     * @return  string
+     */
+    public function getTitle(int $id): string;
+
+    /**
+     * Get a description for the content item.
+     *
+     * @param   int  $id  Content item ID
+     *
+     * @return  string
+     */
+    public function getDescription(int $id): string;
+
+    /**
+     * Get the primary image for the content item.
+     *
+     * @param   int  $id  Content item ID
+     *
+     * @return  string  Image path relative to JPATH_ROOT, or empty string
+     */
+    public function getImage(int $id): string;
+}
@@ -0,0 +1,76 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\ContentType;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+
+class HikaShopAdapter implements ContentTypeInterface
+{
+    public function canHandle(string $option, string $view): bool
+    {
+        return $option === 'com_hikashop' && $view === 'product';
+    }
+
+    public function getContentType(): string
+    {
+        return 'com_hikashop';
+    }
+
+    public function getTitle(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('product_name'))
+            ->from($db->quoteName('#__hikashop_product'))
+            ->where($db->quoteName('product_id') . ' = ' . $id);
+
+        $db->setQuery($query);
+
+        return $db->loadResult() ?: '';
+    }
+
+    public function getDescription(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('product_description'))
+            ->from($db->quoteName('#__hikashop_product'))
+            ->where($db->quoteName('product_id') . ' = ' . $id);
+
+        $db->setQuery($query);
+        $text = $db->loadResult() ?: '';
+        $text = strip_tags($text);
+        $text = trim(preg_replace('/\s+/', ' ', $text));
+
+        if (\strlen($text) > 160) {
+            $text = mb_substr($text, 0, 157) . '...';
+        }
+
+        return $text;
+    }
+
+    public function getImage(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('f.file_path'))
+            ->from($db->quoteName('#__hikashop_file', 'f'))
+            ->where($db->quoteName('f.file_ref_id') . ' = ' . $id)
+            ->where($db->quoteName('f.file_type') . ' = ' . $db->quote('product'))
+            ->order($db->quoteName('f.file_ordering') . ' ASC');
+
+        $db->setQuery($query, 0, 1);
+
+        return $db->loadResult() ?: '';
+    }
+}
@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\ContentType;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+
+class K2Adapter implements ContentTypeInterface
+{
+    public function canHandle(string $option, string $view): bool
+    {
+        return $option === 'com_k2' && $view === 'item';
+    }
+
+    public function getContentType(): string
+    {
+        return 'com_k2';
+    }
+
+    public function getTitle(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('title'))
+            ->from($db->quoteName('#__k2_items'))
+            ->where($db->quoteName('id') . ' = ' . $id);
+
+        $db->setQuery($query);
+
+        return $db->loadResult() ?: '';
+    }
+
+    public function getDescription(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('introtext'))
+            ->from($db->quoteName('#__k2_items'))
+            ->where($db->quoteName('id') . ' = ' . $id);
+
+        $db->setQuery($query);
+        $text = $db->loadResult() ?: '';
+        $text = strip_tags($text);
+        $text = trim(preg_replace('/\s+/', ' ', $text));
+
+        if (\strlen($text) > 160) {
+            $text = mb_substr($text, 0, 157) . '...';
+        }
+
+        return $text;
+    }
+
+    public function getImage(int $id): string
+    {
+        // K2 stores images as media/k2/items/cache/{md5}_L.jpg
+        $imagePath = 'media/k2/items/cache/' . md5('Image' . $id) . '_L.jpg';
+
+        if (is_file(JPATH_ROOT . '/' . $imagePath)) {
+            return $imagePath;
+        }
+
+        return '';
+    }
+}
@@ -0,0 +1,82 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\ContentType;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+
+class VirtueMartAdapter implements ContentTypeInterface
+{
+    public function canHandle(string $option, string $view): bool
+    {
+        return $option === 'com_virtuemart' && $view === 'productdetails';
+    }
+
+    public function getContentType(): string
+    {
+        return 'com_virtuemart';
+    }
+
+    public function getTitle(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('product_name'))
+            ->from($db->quoteName('#__virtuemart_products_' . $this->getLangTag()))
+            ->where($db->quoteName('virtuemart_product_id') . ' = ' . $id);
+
+        $db->setQuery($query);
+
+        return $db->loadResult() ?: '';
+    }
+
+    public function getDescription(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('product_s_desc'))
+            ->from($db->quoteName('#__virtuemart_products_' . $this->getLangTag()))
+            ->where($db->quoteName('virtuemart_product_id') . ' = ' . $id);
+
+        $db->setQuery($query);
+        $desc = $db->loadResult() ?: '';
+
+        return strip_tags($desc);
+    }
+
+    public function getImage(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('m.file_url'))
+            ->from($db->quoteName('#__virtuemart_product_medias', 'pm'))
+            ->join('INNER', $db->quoteName('#__virtuemart_medias', 'm') . ' ON ' . $db->quoteName('m.virtuemart_media_id') . ' = ' . $db->quoteName('pm.virtuemart_media_id'))
+            ->where($db->quoteName('pm.virtuemart_product_id') . ' = ' . $id)
+            ->order($db->quoteName('pm.ordering') . ' ASC');
+
+        $db->setQuery($query, 0, 1);
+
+        return $db->loadResult() ?: '';
+    }
+
+    /**
+     * Get the VirtueMart language table suffix.
+     *
+     * @return  string
+     */
+    private function getLangTag(): string
+    {
+        $lang = Factory::getLanguage()->getTag();
+
+        return strtolower(str_replace('-', '_', $lang));
+    }
+}
@@ -0,0 +1,177 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\Controller;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\CMS\Language\Text;
+use Joomla\CMS\MVC\Controller\BaseController;
+use Joomla\CMS\Response\JsonResponse;
+use Joomla\CMS\Session\Session;
+
+class BatchController extends BaseController
+{
+    /**
+     * Count the total articles eligible for batch generation.
+     *
+     * @return  void
+     */
+    public function count(): void
+    {
+        Session::checkToken('get') || jexit(Text::_('JINVALID_TOKEN'));
+
+        if (!Factory::getApplication()->getIdentity()->authorise('core.create', 'com_mokoog')) {
+            throw new \RuntimeException(Text::_('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'), 403);
+        }
+
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select('COUNT(*)')
+            ->from($db->quoteName('#__content', 'c'))
+            ->leftJoin(
+                $db->quoteName('#__mokoog_tags', 't')
+                . ' ON ' . $db->quoteName('t.content_type') . ' = ' . $db->quote('com_content')
+                . ' AND ' . $db->quoteName('t.content_id') . ' = ' . $db->quoteName('c.id')
+            )
+            ->where($db->quoteName('c.state') . ' = 1')
+            ->where($db->quoteName('t.id') . ' IS NULL');
+
+        $db->setQuery($query);
+        $total = (int) $db->loadResult();
+
+        echo new JsonResponse(['total' => $total]);
+
+        Factory::getApplication()->close();
+    }
+
+    /**
+     * Process a chunk of articles for batch OG generation.
+     *
+     * @return  void
+     */
+    public function process(): void
+    {
+        Session::checkToken('get') || jexit(Text::_('JINVALID_TOKEN'));
+
+        if (!Factory::getApplication()->getIdentity()->authorise('core.create', 'com_mokoog')) {
+            throw new \RuntimeException(Text::_('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'), 403);
+        }
+
+        $app    = Factory::getApplication();
+        $offset = $app->getInput()->getInt('offset', 0);
+        $limit  = $app->getInput()->getInt('limit', 50);
+
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName([
+                'c.id', 'c.title', 'c.metadesc', 'c.introtext', 'c.fulltext', 'c.images',
+            ]))
+            ->from($db->quoteName('#__content', 'c'))
+            ->leftJoin(
+                $db->quoteName('#__mokoog_tags', 't')
+                . ' ON ' . $db->quoteName('t.content_type') . ' = ' . $db->quote('com_content')
+                . ' AND ' . $db->quoteName('t.content_id') . ' = ' . $db->quoteName('c.id')
+            )
+            ->where($db->quoteName('c.state') . ' = 1')
+            ->where($db->quoteName('t.id') . ' IS NULL')
+            ->order($db->quoteName('c.id') . ' ASC');
+
+        $db->setQuery($query, $offset, $limit);
+        $articles = $db->loadObjectList();
+
+        $created = 0;
+        $now     = Factory::getDate()->toSql();
+
+        foreach ($articles as $article) {
+            $ogTitle       = $article->title;
+            $ogDescription = $this->extractDescription($article);
+            $ogImage       = $this->extractImage($article);
+
+            $record = (object) [
+                'content_type'   => 'com_content',
+                'content_id'     => (int) $article->id,
+                'og_title'       => $ogTitle,
+                'og_description' => $ogDescription,
+                'og_image'       => $ogImage,
+                'og_type'        => 'article',
+                'seo_title'      => '',
+                'meta_description' => $article->metadesc ?: '',
+                'robots'         => '',
+                'canonical_url'  => '',
+                'published'      => 1,
+                'created'        => $now,
+                'modified'       => $now,
+            ];
+
+            $db->insertObject('#__mokoog_tags', $record);
+            $created++;
+        }
+
+        echo new JsonResponse([
+            'created'   => $created,
+            'offset'    => $offset,
+            'processed' => $offset + $created,
+        ]);
+
+        $app->close();
+    }
+
+    /**
+     * Extract a description from article content.
+     *
+     * @param   object  $article  Article record
+     *
+     * @return  string
+     */
+    private function extractDescription(object $article): string
+    {
+        // Prefer meta description if set
+        if (!empty($article->metadesc)) {
+            return $article->metadesc;
+        }
+
+        // Fall back to intro text
+        $text = $article->introtext ?: $article->fulltext;
+        $text = strip_tags($text);
+        $text = trim(preg_replace('/\s+/', ' ', $text));
+
+        if (\strlen($text) > 160) {
+            $text = mb_substr($text, 0, 157) . '...';
+        }
+
+        return $text;
+    }
+
+    /**
+     * Extract the best image from article data.
+     *
+     * @param   object  $article  Article record
+     *
+     * @return  string
+     */
+    private function extractImage(object $article): string
+    {
+        if (!empty($article->images)) {
+            $images = json_decode($article->images, true);
+
+            if (!empty($images['image_fulltext'])) {
+                return $images['image_fulltext'];
+            }
+
+            if (!empty($images['image_intro'])) {
+                return $images['image_intro'];
+            }
+        }
+
+        return '';
+    }
+}
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -0,0 +1,245 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\Controller;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\CMS\Language\Text;
+use Joomla\CMS\MVC\Controller\BaseController;
+use Joomla\CMS\Session\Session;
+
+class ImportExportController extends BaseController
+{
+    /**
+     * Maximum upload file size in bytes (2 MB).
+     */
+    private const MAX_FILE_SIZE = 2 * 1024 * 1024;
+
+    /**
+     * Allowed content_type patterns for import.
+     */
+    private const CONTENT_TYPE_PATTERN = '/^[a-z][a-z0-9_.]*$/';
+
+    /**
+     * Export all OG tags as CSV.
+     *
+     * @return  void
+     */
+    public function export(): void
+    {
+        Session::checkToken('get') || jexit(Text::_('JINVALID_TOKEN'));
+
+        if (!Factory::getApplication()->getIdentity()->authorise('core.manage', 'com_mokoog')) {
+            throw new \RuntimeException(Text::_('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'), 403);
+        }
+
+        $app = Factory::getApplication();
+        $db  = Factory::getDbo();
+
+        // Join with #__content to get article titles for reference
+        $query = $db->getQuery(true)
+            ->select([
+                $db->quoteName('t.content_type'),
+                $db->quoteName('t.content_id'),
+                'COALESCE(' . $db->quoteName('c.title') . ', ' . $db->quote('') . ') AS ' . $db->quoteName('article_title'),
+                $db->quoteName('t.og_title'),
+                $db->quoteName('t.og_description'),
+                $db->quoteName('t.og_image'),
+                $db->quoteName('t.og_type'),
+                $db->quoteName('t.seo_title'),
+                $db->quoteName('t.meta_description'),
+                $db->quoteName('t.robots'),
+                $db->quoteName('t.canonical_url'),
+            ])
+            ->from($db->quoteName('#__mokoog_tags', 't'))
+            ->leftJoin(
+                $db->quoteName('#__content', 'c')
+                . ' ON ' . $db->quoteName('t.content_type') . ' = ' . $db->quote('com_content')
+                . ' AND ' . $db->quoteName('t.content_id') . ' = ' . $db->quoteName('c.id')
+            )
+            ->order($db->quoteName('t.content_type') . ', ' . $db->quoteName('t.content_id'));
+
+        $db->setQuery($query);
+        $rows = $db->loadAssocList();
+
+        // Send CSV headers
+        $app->setHeader('Content-Type', 'text/csv; charset=utf-8');
+        $app->setHeader('Content-Disposition', 'attachment; filename="mokoog_tags_export.csv"');
+        $app->sendHeaders();
+
+        $output = fopen('php://output', 'w');
+
+        // Header row
+        fputcsv($output, [
+            'content_type', 'content_id', 'article_title',
+            'og_title', 'og_description', 'og_image', 'og_type',
+            'seo_title', 'meta_description', 'robots', 'canonical_url',
+        ]);
+
+        foreach ($rows as $row) {
+            fputcsv($output, $row);
+        }
+
+        fclose($output);
+        $app->close();
+    }
+
+    /**
+     * Import OG tags from uploaded CSV.
+     *
+     * @return  void
+     */
+    public function import(): void
+    {
+        Session::checkToken() || jexit(Text::_('JINVALID_TOKEN'));
+
+        $identity = Factory::getApplication()->getIdentity();
+
+        if (!$identity->authorise('core.create', 'com_mokoog') || !$identity->authorise('core.edit', 'com_mokoog')) {
+            throw new \RuntimeException(Text::_('JLIB_APPLICATION_ERROR_ACCESS_FORBIDDEN'), 403);
+        }
+
+        $app   = Factory::getApplication();
+        $input = $app->getInput();
+        $files = $input->files->get('jform', [], 'array');
+
+        if (empty($files['csv_file']['tmp_name'])) {
+            $app->enqueueMessage(Text::_('COM_MOKOOG_IMPORT_NO_FILE'), 'error');
+            $app->redirect('index.php?option=com_mokoog&view=tags');
+
+            return;
+        }
+
+        $csvFile = $files['csv_file'];
+
+        // Validate file extension
+        $ext = strtolower(pathinfo($csvFile['name'] ?? '', PATHINFO_EXTENSION));
+
+        if ($ext !== 'csv') {
+            $app->enqueueMessage(Text::_('COM_MOKOOG_IMPORT_INVALID_TYPE'), 'error');
+            $app->redirect('index.php?option=com_mokoog&view=tags');
+
+            return;
+        }
+
+        // Validate MIME type
+        $allowedMimes = ['text/csv', 'text/plain', 'application/csv', 'application/vnd.ms-excel'];
+
+        if (!empty($csvFile['type']) && !\in_array($csvFile['type'], $allowedMimes, true)) {
+            $app->enqueueMessage(Text::_('COM_MOKOOG_IMPORT_INVALID_TYPE'), 'error');
+            $app->redirect('index.php?option=com_mokoog&view=tags');
+
+            return;
+        }
+
+        // Validate file size
+        if (($csvFile['size'] ?? 0) > self::MAX_FILE_SIZE) {
+            $app->enqueueMessage(Text::sprintf('COM_MOKOOG_IMPORT_FILE_TOO_LARGE', '2 MB'), 'error');
+            $app->redirect('index.php?option=com_mokoog&view=tags');
+
+            return;
+        }
+
+        $tmpFile = $csvFile['tmp_name'];
+        $handle  = fopen($tmpFile, 'r');
+
+        if (!$handle) {
+            $app->enqueueMessage(Text::_('COM_MOKOOG_IMPORT_READ_ERROR'), 'error');
+            $app->redirect('index.php?option=com_mokoog&view=tags');
+
+            return;
+        }
+
+        $db      = Factory::getDbo();
+        $header  = fgetcsv($handle);
+        $created = 0;
+        $updated = 0;
+        $skipped = 0;
+        $now     = Factory::getDate()->toSql();
+
+        while (($row = fgetcsv($handle)) !== false) {
+            if (\count($row) < 7) {
+                $skipped++;
+
+                continue;
+            }
+
+            $contentType = trim($row[0]);
+            $contentId   = (int) $row[1];
+            // $row[2] = article_title (informational, skip)
+            $ogTitle       = trim($row[3] ?? '');
+            $ogDescription = trim($row[4] ?? '');
+            $ogImage       = trim($row[5] ?? '');
+            $ogType        = trim($row[6] ?? 'article');
+            $seoTitle      = trim($row[7] ?? '');
+            $metaDesc      = trim($row[8] ?? '');
+            $robots        = trim($row[9] ?? '');
+            $canonicalUrl  = trim($row[10] ?? '');
+
+            if (empty($contentType) || $contentId <= 0) {
+                $skipped++;
+
+                continue;
+            }
+
+            // Validate content_type against allowed pattern
+            if (!preg_match(self::CONTENT_TYPE_PATTERN, $contentType)) {
+                $skipped++;
+
+                continue;
+            }
+
+            // Check for existing record
+            $query = $db->getQuery(true)
+                ->select($db->quoteName('id'))
+                ->from($db->quoteName('#__mokoog_tags'))
+                ->where($db->quoteName('content_type') . ' = ' . $db->quote($contentType))
+                ->where($db->quoteName('content_id') . ' = ' . $contentId);
+
+            $db->setQuery($query);
+            $existingId = $db->loadResult();
+
+            $record = (object) [
+                'content_type'     => $contentType,
+                'content_id'       => $contentId,
+                'og_title'         => $ogTitle,
+                'og_description'   => $ogDescription,
+                'og_image'         => $ogImage,
+                'og_type'          => $ogType,
+                'seo_title'        => $seoTitle,
+                'meta_description' => $metaDesc,
+                'robots'           => $robots,
+                'canonical_url'    => $canonicalUrl,
+                'published'        => 1,
+                'modified'         => $now,
+            ];
+
+            if ($existingId) {
+                $record->id = $existingId;
+                $db->updateObject('#__mokoog_tags', $record, 'id');
+                $updated++;
+            } else {
+                $record->created = $now;
+                $db->insertObject('#__mokoog_tags', $record);
+                $created++;
+            }
+        }
+
+        fclose($handle);
+
+        $app->enqueueMessage(
+            Text::sprintf('COM_MOKOOG_IMPORT_RESULT', $created, $updated, $skipped),
+            'success'
+        );
+        $app->redirect('index.php?option=com_mokoog&view=tags');
+    }
+}
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  com_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Component\MokoOG\Administrator\Model;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\CMS\MVC\Model\AdminModel;
+
+class TagModel extends AdminModel
+{
+    /**
+     * Get the form for the item.
+     *
+     * @param   array  $data      Form data
+     * @param   bool   $loadData  Load data from state
+     *
+     * @return  \Joomla\CMS\Form\Form|false
+     */
+    public function getForm($data = [], $loadData = true)
+    {
+        $form = $this->loadForm(
+            'com_mokoog.tag',
+            'tag',
+            ['control' => 'jform', 'load_data' => $loadData]
+        );
+
+        return $form ?: false;
+    }
+
+    /**
+     * Load the form data.
+     *
+     * @return  object
+     */
+    protected function loadFormData(): object
+    {
+        $data = Factory::getApplication()->getUserState('com_mokoog.edit.tag.data', []);
+
+        if (empty($data)) {
+            $data = $this->getItem();
+        }
+
+        return $data;
+    }
+
+    /**
+     * Get the table class name.
+     *
+     * @param   string  $name    Table name
+     * @param   string  $prefix  Table prefix
+     * @param   array   $options Table options
+     *
+     * @return  \Joomla\CMS\Table\Table
+     */
+    public function getTable($name = 'Tag', $prefix = 'Administrator', $options = [])
+    {
+        return parent::getTable($name, $prefix, $options);
+    }
+}
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -39,6 +39,20 @@ class HtmlView extends BaseHtmlView
     */
    protected $state;

+    /**
+     * The filter form.
+     *
+     * @var \Joomla\CMS\Form\Form|null
+     */
+    public $filterForm;
+
+    /**
+     * The active filters.
+     *
+     * @var array
+     */
+    public $activeFilters = [];
+
    /**
     * Display the view.
     *
@@ -48,9 +62,11 @@ class HtmlView extends BaseHtmlView
     */
    public function display($tpl = null): void
    {
-        $this->items      = $this->get('Items');
-        $this->pagination = $this->get('Pagination');
-        $this->state      = $this->get('State');
+        $this->items         = $this->get('Items');
+        $this->pagination    = $this->get('Pagination');
+        $this->state         = $this->get('State');
+        $this->filterForm    = $this->get('FilterForm');
+        $this->activeFilters = $this->get('ActiveFilters');

        $this->addToolbar();

@@ -65,6 +81,8 @@ class HtmlView extends BaseHtmlView
    protected function addToolbar(): void
    {
        ToolbarHelper::title(Text::_('COM_MOKOOG_TAGS_TITLE'), 'bookmark');
+        ToolbarHelper::custom('batch.generate', 'refresh', '', 'COM_MOKOOG_TOOLBAR_BATCH_GENERATE', false);
+        ToolbarHelper::custom('importexport.export', 'download', '', 'COM_MOKOOG_TOOLBAR_EXPORT', false);
        ToolbarHelper::deleteList('JGLOBAL_CONFIRM_DELETE', 'tags.delete');
        ToolbarHelper::preferences('com_mokoog');
    }
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  com_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -14,14 +14,18 @@ use Joomla\CMS\HTML\HTMLHelper;
 use Joomla\CMS\Language\Text;
 use Joomla\CMS\Layout\LayoutHelper;
 use Joomla\CMS\Router\Route;
+use Joomla\CMS\Uri\Uri;
+use Joomla\CMS\Session\Session;

 /** @var \Joomla\Component\MokoOG\Administrator\View\Tags\HtmlView $this */

+$token = Session::getFormToken();
 ?>
 <form action="<?php echo Route::_('index.php?option=com_mokoog&view=tags'); ?>" method="post" name="adminForm" id="adminForm">
    <div class="row">
        <div class="col-md-12">
            <div id="j-main-container" class="j-main-container">
+                <?php echo LayoutHelper::render('joomla.searchtools.default', ['view' => $this]); ?>

                <?php if (empty($this->items)) : ?>
                    <div class="alert alert-info">
@@ -50,9 +54,15 @@ use Joomla\CMS\Router\Route;
                                <th scope="col" class="w-10">
                                    <?php echo Text::_('COM_MOKOOG_HEADING_IMAGE'); ?>
                                </th>
+                                <th scope="col" class="w-10">
+                                    <?php echo Text::_('COM_MOKOOG_HEADING_SEO'); ?>
+                                </th>
                                <th scope="col" class="w-10">
                                    <?php echo Text::_('JSTATUS'); ?>
                                </th>
+                                <th scope="col" class="w-10">
+                                    <?php echo Text::_('COM_MOKOOG_HEADING_DEBUG'); ?>
+                                </th>
                                <th scope="col" class="w-10">
                                    <?php echo Text::_('COM_MOKOOG_HEADING_MODIFIED'); ?>
                                </th>
@@ -83,9 +93,50 @@ use Joomla\CMS\Router\Route;
                                            <span class="icon-minus-circle text-muted" aria-hidden="true"></span>
                                        <?php endif; ?>
                                    </td>
+                                    <td>
+                                        <?php
+                                        $seoIssues = [];
+
+                                        if (empty($item->meta_description)) {
+                                            $seoIssues[] = Text::_('COM_MOKOOG_SEO_MISSING_DESC');
+                                        }
+
+                                        if (!empty($item->seo_title) && \strlen($item->seo_title) > 60) {
+                                            $seoIssues[] = Text::_('COM_MOKOOG_SEO_TITLE_LONG');
+                                        }
+
+                                        if (!empty($item->robots) && str_contains($item->robots, 'noindex')) {
+                                            $seoIssues[] = Text::_('COM_MOKOOG_SEO_NOINDEX');
+                                        }
+
+                                        if (empty($seoIssues)) : ?>
+                                            <span class="badge bg-success"><?php echo Text::_('COM_MOKOOG_SEO_OK'); ?></span>
+                                        <?php else : ?>
+                                            <?php foreach ($seoIssues as $issue) : ?>
+                                                <span class="badge bg-warning text-dark"><?php echo $issue; ?></span>
+                                            <?php endforeach; ?>
+                                        <?php endif; ?>
+                                    </td>
                                    <td>
                                        <?php echo $item->published ? Text::_('JPUBLISHED') : Text::_('JUNPUBLISHED'); ?>
                                    </td>
+                                    <td class="mokoog-debug-links">
+                                        <?php
+                                        // Build frontend URL for this content item
+                                        if ($item->content_type === 'com_content') {
+                                            $debugUrl = Uri::root() . 'index.php?option=com_content&view=article&id=' . (int) $item->content_id;
+                                        } elseif ($item->content_type === 'menu') {
+                                            $debugUrl = Uri::root() . 'index.php?Itemid=' . (int) $item->content_id;
+                                        } elseif ($item->content_type === 'com_content.category') {
+                                            $debugUrl = Uri::root() . 'index.php?option=com_content&view=category&id=' . (int) $item->content_id;
+                                        } else {
+                                            $debugUrl = Uri::root();
+                                        }
+                                        ?>
+                                        <a href="https://developers.facebook.com/tools/debug/?q=<?php echo urlencode($debugUrl); ?>" target="_blank" rel="noopener" title="Facebook Debugger" class="btn btn-sm btn-outline-primary">FB</a>
+                                        <a href="https://www.linkedin.com/post-inspector/inspect/<?php echo urlencode($debugUrl); ?>" target="_blank" rel="noopener" title="LinkedIn Inspector" class="btn btn-sm btn-outline-info">LI</a>
+                                        <a href="https://search.google.com/test/rich-results?url=<?php echo urlencode($debugUrl); ?>" target="_blank" rel="noopener" title="Google Rich Results" class="btn btn-sm btn-outline-success">G</a>
+                                    </td>
                                    <td>
                                        <?php echo HTMLHelper::_('date', $item->modified, Text::_('DATE_FORMAT_LC4')); ?>
                                    </td>
@@ -107,3 +158,85 @@ use Joomla\CMS\Router\Route;
        </div>
    </div>
 </form>
+
+<!-- Batch Generation Progress -->
+<div id="mokoog-batch-panel" style="display:none;" class="card mt-3">
+    <div class="card-body">
+        <h4><?php echo Text::_('COM_MOKOOG_BATCH_TITLE'); ?></h4>
+        <div class="progress mb-2">
+            <div id="mokoog-batch-bar" class="progress-bar progress-bar-striped progress-bar-animated" role="progressbar" style="width: 0%">0%</div>
+        </div>
+        <p id="mokoog-batch-status"></p>
+    </div>
+</div>
+
+<script>
+document.addEventListener('DOMContentLoaded', function() {
+    // Intercept the batch.generate toolbar button
+    var origSubmitbutton = Joomla.submitbutton;
+    Joomla.submitbutton = function(task) {
+        if (task === 'batch.generate') {
+            mokoogBatchGenerate();
+            return;
+        }
+        if (origSubmitbutton) {
+            origSubmitbutton(task);
+        }
+    };
+
+    function mokoogBatchGenerate() {
+        var panel = document.getElementById('mokoog-batch-panel');
+        var bar = document.getElementById('mokoog-batch-bar');
+        var status = document.getElementById('mokoog-batch-status');
+        var token = '<?php echo $token; ?>';
+        var chunkSize = 50;
+
+        panel.style.display = 'block';
+        status.textContent = '<?php echo Text::_('COM_MOKOOG_BATCH_COUNTING', true); ?>';
+
+        // Step 1: Count eligible articles
+        fetch('index.php?option=com_mokoog&task=batch.count&format=json&' + token + '=1')
+            .then(function(r) { return r.json(); })
+            .then(function(resp) {
+                var total = resp.data.total;
+                if (total === 0) {
+                    bar.style.width = '100%';
+                    bar.textContent = '100%';
+                    bar.classList.remove('progress-bar-animated');
+                    bar.classList.add('bg-success');
+                    status.textContent = '<?php echo Text::_('COM_MOKOOG_BATCH_NONE', true); ?>';
+                    return;
+                }
+                status.textContent = total + ' <?php echo Text::_('COM_MOKOOG_BATCH_FOUND', true); ?>';
+                processChunk(0, total, chunkSize, token, bar, status);
+            })
+            .catch(function(err) {
+                status.textContent = '<?php echo Text::_('COM_MOKOOG_BATCH_ERROR', true); ?> ' + err.message;
+            });
+    }
+
+    function processChunk(offset, total, chunkSize, token, bar, status) {
+        fetch('index.php?option=com_mokoog&task=batch.process&format=json&offset=' + offset + '&limit=' + chunkSize + '&' + token + '=1')
+            .then(function(r) { return r.json(); })
+            .then(function(resp) {
+                var processed = resp.data.processed;
+                var pct = Math.min(100, Math.round((processed / total) * 100));
+                bar.style.width = pct + '%';
+                bar.textContent = pct + '%';
+                status.textContent = processed + ' / ' + total + ' <?php echo Text::_('COM_MOKOOG_BATCH_PROCESSED', true); ?>';
+
+                if (processed < total) {
+                    processChunk(processed, total, chunkSize, token, bar, status);
+                } else {
+                    bar.classList.remove('progress-bar-animated');
+                    bar.classList.add('bg-success');
+                    status.textContent = '<?php echo Text::_('COM_MOKOOG_BATCH_COMPLETE', true); ?> ' + total + ' articles.';
+                    setTimeout(function() { location.reload(); }, 2000);
+                }
+            })
+            .catch(function(err) {
+                status.textContent = '<?php echo Text::_('COM_MOKOOG_BATCH_ERROR', true); ?> ' + err.message;
+            });
+    }
+});
+</script>
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_content_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -50,5 +50,48 @@
                <option value="video.other">Video</option>
            </field>
        </fieldset>
+        <fieldset name="mokoog_seo" label="PLG_CONTENT_MOKOOG_FIELDSET_SEO_LABEL"
+                  description="PLG_CONTENT_MOKOOG_FIELDSET_SEO_DESC">
+            <field
+                name="seo_title"
+                type="text"
+                label="PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE"
+                description="PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE_DESC"
+                filter="string"
+                maxlength="70"
+            />
+            <field
+                name="meta_description"
+                type="textarea"
+                label="PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION"
+                description="PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION_DESC"
+                filter="string"
+                rows="3"
+                maxlength="200"
+            />
+            <field
+                name="robots"
+                type="list"
+                label="PLG_CONTENT_MOKOOG_FIELD_ROBOTS"
+                description="PLG_CONTENT_MOKOOG_FIELD_ROBOTS_DESC"
+                default=""
+                multiple="true"
+            >
+                <option value="">PLG_CONTENT_MOKOOG_ROBOTS_DEFAULT</option>
+                <option value="noindex">noindex</option>
+                <option value="nofollow">nofollow</option>
+                <option value="nosnippet">nosnippet</option>
+                <option value="noarchive">noarchive</option>
+                <option value="noimageindex">noimageindex</option>
+            </field>
+            <field
+                name="canonical_url"
+                type="url"
+                label="PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL"
+                description="PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL_DESC"
+                filter="url"
+                validate="url"
+            />
+        </fieldset>
    </fields>
 </form>
@@ -1,4 +1,4 @@
-; MokoOpenGraph - Content Plugin Language File
+; MokoJoomOpenGraph - Content Plugin Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

@@ -13,3 +13,16 @@ PLG_CONTENT_MOKOOG_FIELD_OG_IMAGE="OG Image"
 PLG_CONTENT_MOKOOG_FIELD_OG_IMAGE_DESC="Custom image for social sharing. Recommended: 1200x630px. Leave blank to use the article image."
 PLG_CONTENT_MOKOOG_FIELD_OG_TYPE="OG Type"
 PLG_CONTENT_MOKOOG_FIELD_OG_TYPE_DESC="The Open Graph content type for this page."
+
+PLG_CONTENT_MOKOOG_FIELDSET_SEO_LABEL="SEO Meta Tags"
+PLG_CONTENT_MOKOOG_FIELDSET_SEO_DESC="Control search engine meta tags for this page."
+
+PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE="SEO Title"
+PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE_DESC="Custom <title> tag. 50-60 characters recommended. Leave blank to use the default page title."
+PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION="Meta Description"
+PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION_DESC="Custom meta description. 150-160 characters recommended. Leave blank to use the default."
+PLG_CONTENT_MOKOOG_FIELD_ROBOTS="Robots Directive"
+PLG_CONTENT_MOKOOG_FIELD_ROBOTS_DESC="Search engine indexing directives for this page. Leave blank for default (index, follow)."
+PLG_CONTENT_MOKOOG_ROBOTS_DEFAULT="- Use default (index, follow) -"
+PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL="Canonical URL"
+PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL_DESC="Override the canonical URL for this page. Leave blank to use the current URL."
@@ -1,6 +1,6 @@
-; MokoOpenGraph - Content Plugin System Language File
+; MokoJoomOpenGraph - Content Plugin System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-PLG_CONTENT_MOKOOG="Content - MokoOpenGraph"
+PLG_CONTENT_MOKOOG="Content - MokoJoomOpenGraph"
 PLG_CONTENT_MOKOOG_DESCRIPTION="Adds Open Graph fields to article and menu item edit forms for per-page social sharing control."
@@ -1,4 +1,4 @@
-; MokoOpenGraph - Content Plugin Language File
+; MokoJoomOpenGraph - Content Plugin Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

@@ -13,3 +13,16 @@ PLG_CONTENT_MOKOOG_FIELD_OG_IMAGE="OG Image"
 PLG_CONTENT_MOKOOG_FIELD_OG_IMAGE_DESC="Custom image for social sharing. Recommended: 1200x630px. Leave blank to use the article image."
 PLG_CONTENT_MOKOOG_FIELD_OG_TYPE="OG Type"
 PLG_CONTENT_MOKOOG_FIELD_OG_TYPE_DESC="The Open Graph content type for this page."
+
+PLG_CONTENT_MOKOOG_FIELDSET_SEO_LABEL="SEO Meta Tags"
+PLG_CONTENT_MOKOOG_FIELDSET_SEO_DESC="Control search engine meta tags for this page."
+
+PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE="SEO Title"
+PLG_CONTENT_MOKOOG_FIELD_SEO_TITLE_DESC="Custom <title> tag. 50-60 characters recommended. Leave blank to use the default page title."
+PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION="Meta Description"
+PLG_CONTENT_MOKOOG_FIELD_META_DESCRIPTION_DESC="Custom meta description. 150-160 characters recommended. Leave blank to use the default."
+PLG_CONTENT_MOKOOG_FIELD_ROBOTS="Robots Directive"
+PLG_CONTENT_MOKOOG_FIELD_ROBOTS_DESC="Search engine indexing directives for this page. Leave blank for default (index, follow)."
+PLG_CONTENT_MOKOOG_ROBOTS_DEFAULT="- Use default (index, follow) -"
+PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL="Canonical URL"
+PLG_CONTENT_MOKOOG_FIELD_CANONICAL_URL_DESC="Override the canonical URL for this page. Leave blank to use the current URL."
@@ -1,6 +1,6 @@
-; MokoOpenGraph - Content Plugin System Language File
+; MokoJoomOpenGraph - Content Plugin System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-PLG_CONTENT_MOKOOG="Content - MokoOpenGraph"
+PLG_CONTENT_MOKOOG="Content - MokoJoomOpenGraph"
 PLG_CONTENT_MOKOOG_DESCRIPTION="Adds Open Graph fields to article and menu item edit forms for per-page social sharing control."
@@ -0,0 +1,104 @@
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_content_mokoog
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GPL-3.0-or-later
+ */
+
+.mokoog-preview-wrapper {
+    margin: 15px 0;
+    padding: 15px;
+    background: #f8f9fa;
+    border-radius: 8px;
+    border: 1px solid #dee2e6;
+}
+
+.mokoog-preview-heading {
+    margin: 0 0 12px;
+    font-size: 14px;
+    color: #666;
+}
+
+.mokoog-platform-label {
+    display: block;
+    color: #999;
+    text-transform: uppercase;
+    font-size: 11px;
+    font-weight: 600;
+    margin-top: 16px;
+    margin-bottom: 4px;
+}
+
+.mokoog-platform-label:first-of-type {
+    margin-top: 0;
+}
+
+.mokoog-card {
+    overflow: hidden;
+    max-width: 500px;
+    background: #fff;
+}
+
+.mokoog-card-fb {
+    border: 1px solid #ddd;
+    border-radius: 3px;
+}
+
+.mokoog-card-tw {
+    border: 1px solid #cfd9de;
+    border-radius: 16px;
+}
+
+.mokoog-card-img {
+    height: 260px;
+    background: #e4e6eb center / cover no-repeat;
+}
+
+.mokoog-card-body {
+    padding: 10px 12px;
+    border-top: 1px solid #ddd;
+}
+
+.mokoog-card-tw .mokoog-card-body {
+    border-top-color: #cfd9de;
+}
+
+.mokoog-card-domain {
+    font-size: 11px;
+    color: #65676b;
+    text-transform: uppercase;
+}
+
+.mokoog-card-tw .mokoog-card-domain {
+    font-size: 13px;
+    text-transform: none;
+    margin-top: 4px;
+}
+
+.mokoog-card-title {
+    font-size: 16px;
+    font-weight: 600;
+    color: #1d2129;
+    margin: 3px 0 2px;
+    line-height: 1.3;
+}
+
+.mokoog-card-tw .mokoog-card-title {
+    font-size: 15px;
+    font-weight: 700;
+    color: #0f1419;
+}
+
+.mokoog-card-desc {
+    font-size: 14px;
+    color: #65676b;
+    line-height: 1.4;
+    max-height: 2.8em;
+    overflow: hidden;
+}
+
+.mokoog-card-tw .mokoog-card-desc {
+    font-size: 15px;
+    color: #536471;
+    margin-top: 2px;
+}
@@ -0,0 +1,20 @@
+{
+    "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
+    "name": "plg_content_mokoog",
+    "version": "01.00.00",
+    "description": "MokoJoomOpenGraph Content Plugin Assets",
+    "license": "GPL-3.0-or-later",
+    "assets": [
+        {
+            "name": "plg_content_mokoog.preview",
+            "type": "style",
+            "uri": "plg_content_mokoog/css/preview.css"
+        },
+        {
+            "name": "plg_content_mokoog.preview",
+            "type": "script",
+            "uri": "plg_content_mokoog/js/preview.js",
+            "dependencies": ["core"]
+        }
+    ]
+}
@@ -0,0 +1,170 @@
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_content_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GPL-3.0-or-later
+ *
+ * Live social sharing preview for article/menu item editor.
+ */
+document.addEventListener('DOMContentLoaded', function () {
+    'use strict';
+
+    var fields = {
+        ogTitle: document.getElementById('jform_mokoog_og_title'),
+        ogDesc: document.getElementById('jform_mokoog_og_description'),
+        ogImage: document.getElementById('jform_mokoog_og_image'),
+        articleTitle: document.getElementById('jform_title'),
+        metaDesc: document.getElementById('jform_metadesc')
+    };
+
+    // Find the mokoog fieldset and insert preview after it
+    var fieldset = document.querySelector('[data-showon-id="mokoog"]') ||
+        document.getElementById('attrib-mokoog') ||
+        document.querySelector('fieldset.mokoog') ||
+        document.querySelector('[id*="mokoog"]');
+
+    if (!fieldset) {
+        return;
+    }
+
+    // Build preview DOM safely (no innerHTML with user data)
+    var preview = document.createElement('div');
+    preview.id = 'mokoog-preview';
+
+    var wrapper = document.createElement('div');
+    wrapper.className = 'mokoog-preview-wrapper';
+
+    var heading = document.createElement('h4');
+    heading.className = 'mokoog-preview-heading';
+    heading.textContent = 'Social Sharing Preview';
+    wrapper.appendChild(heading);
+
+    // Facebook preview card
+    var fbLabel = document.createElement('small');
+    fbLabel.className = 'mokoog-platform-label';
+    fbLabel.textContent = 'Facebook';
+    wrapper.appendChild(fbLabel);
+
+    var fbCard = document.createElement('div');
+    fbCard.className = 'mokoog-card mokoog-card-fb';
+
+    var fbImg = document.createElement('div');
+    fbImg.id = 'mokoog-fb-img';
+    fbImg.className = 'mokoog-card-img';
+    fbCard.appendChild(fbImg);
+
+    var fbBody = document.createElement('div');
+    fbBody.className = 'mokoog-card-body';
+
+    var fbDomain = document.createElement('div');
+    fbDomain.id = 'mokoog-fb-domain';
+    fbDomain.className = 'mokoog-card-domain';
+    fbBody.appendChild(fbDomain);
+
+    var fbTitle = document.createElement('div');
+    fbTitle.id = 'mokoog-fb-title';
+    fbTitle.className = 'mokoog-card-title';
+    fbBody.appendChild(fbTitle);
+
+    var fbDesc = document.createElement('div');
+    fbDesc.id = 'mokoog-fb-desc';
+    fbDesc.className = 'mokoog-card-desc';
+    fbBody.appendChild(fbDesc);
+
+    fbCard.appendChild(fbBody);
+    wrapper.appendChild(fbCard);
+
+    // Twitter preview card
+    var twLabel = document.createElement('small');
+    twLabel.className = 'mokoog-platform-label';
+    twLabel.textContent = 'Twitter / X';
+    wrapper.appendChild(twLabel);
+
+    var twCard = document.createElement('div');
+    twCard.className = 'mokoog-card mokoog-card-tw';
+
+    var twImg = document.createElement('div');
+    twImg.id = 'mokoog-tw-img';
+    twImg.className = 'mokoog-card-img';
+    twCard.appendChild(twImg);
+
+    var twBody = document.createElement('div');
+    twBody.className = 'mokoog-card-body';
+
+    var twTitle = document.createElement('div');
+    twTitle.id = 'mokoog-tw-title';
+    twTitle.className = 'mokoog-card-title';
+    twBody.appendChild(twTitle);
+
+    var twDesc = document.createElement('div');
+    twDesc.id = 'mokoog-tw-desc';
+    twDesc.className = 'mokoog-card-desc';
+    twBody.appendChild(twDesc);
+
+    var twDomain = document.createElement('div');
+    twDomain.id = 'mokoog-tw-domain';
+    twDomain.className = 'mokoog-card-domain';
+    twBody.appendChild(twDomain);
+
+    twCard.appendChild(twBody);
+    wrapper.appendChild(twCard);
+
+    preview.appendChild(wrapper);
+    fieldset.parentNode.insertBefore(preview, fieldset.nextSibling);
+
+    var domain = window.location.hostname;
+
+    function updatePreview() {
+        var title = (fields.ogTitle && fields.ogTitle.value) ||
+            (fields.articleTitle && fields.articleTitle.value) || 'Page Title';
+        var desc = (fields.ogDesc && fields.ogDesc.value) ||
+            (fields.metaDesc && fields.metaDesc.value) || 'Page description will appear here...';
+        var img = '';
+
+        if (fields.ogImage) {
+            img = fields.ogImage.value;
+        }
+
+        if (title.length > 65) title = title.substring(0, 62) + '...';
+        if (desc.length > 160) desc = desc.substring(0, 157) + '...';
+
+        // Facebook
+        document.getElementById('mokoog-fb-title').textContent = title;
+        document.getElementById('mokoog-fb-desc').textContent = desc;
+        document.getElementById('mokoog-fb-domain').textContent = domain;
+        var fbImgEl = document.getElementById('mokoog-fb-img');
+        if (img) {
+            fbImgEl.style.backgroundImage = 'url(' + encodeURI(img) + ')';
+            fbImgEl.style.display = '';
+        } else {
+            fbImgEl.style.display = 'none';
+        }
+
+        // Twitter
+        document.getElementById('mokoog-tw-title').textContent = title;
+        document.getElementById('mokoog-tw-desc').textContent = desc;
+        document.getElementById('mokoog-tw-domain').textContent = domain;
+        var twImgEl = document.getElementById('mokoog-tw-img');
+        if (img) {
+            twImgEl.style.backgroundImage = 'url(' + encodeURI(img) + ')';
+            twImgEl.style.display = '';
+        } else {
+            twImgEl.style.display = 'none';
+        }
+    }
+
+    Object.values(fields).forEach(function (el) {
+        if (el) {
+            el.addEventListener('input', updatePreview);
+            el.addEventListener('change', updatePreview);
+        }
+    });
+
+    if (fields.ogImage) {
+        var observer = new MutationObserver(updatePreview);
+        observer.observe(fields.ogImage, { attributes: true, attributeFilter: ['value'] });
+    }
+
+    updatePreview();
+});
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_content_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,14 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_content_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE
 -->
 <extension type="plugin" group="content" method="upgrade">
-    <name>Content - MokoOpenGraph</name>
-    <version>01.00.00</version>
+    <name>Content - MokoJoomOpenGraph</name>
+    <version>01.00.01-rc</version>
    <creationDate>2026-05-23</creationDate>
    <author>Moko Consulting</author>
    <authorEmail>hello@mokoconsulting.tech</authorEmail>
@@ -27,6 +27,12 @@
        <folder>language</folder>
    </files>

+    <media destination="plg_content_mokoog" folder="media">
+        <filename>joomla.asset.json</filename>
+        <folder>js</folder>
+        <folder>css</folder>
+    </media>
+
    <languages>
        <language tag="en-GB">language/en-GB/plg_content_mokoog.ini</language>
        <language tag="en-GB">language/en-GB/plg_content_mokoog.sys.ini</language>
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_content_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_content_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -56,10 +56,11 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface

        $formName = $form->getName();

-        // Add OG fields to article and menu item edit forms
+        // Add OG fields to article, menu item, and category edit forms
        $supportedForms = [
            'com_content.article',
            'com_menus.item',
+            'com_categories.categorycom_content',
        ];

        if (!\in_array($formName, $supportedForms, true)) {
@@ -71,6 +72,12 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
        Form::addFormPath($formPath);
        $form->loadFile('mokoog', false);

+        // Load live preview assets
+        $wa = $this->getApplication()->getDocument()->getWebAssetManager();
+        $wa->getRegistry()->addRegistryFile('media/plg_content_mokoog/joomla.asset.json');
+        $wa->useStyle('plg_content_mokoog.preview');
+        $wa->useScript('plg_content_mokoog.preview');
+
        // If editing an existing item, load saved OG data
        $id = 0;

@@ -81,8 +88,14 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
        }

        if ($id > 0) {
-            $contentType = ($formName === 'com_menus.item') ? 'menu' : 'com_content';
-            $ogData      = $this->loadOgData($contentType, $id);
+            $formTypeMap = [
+                'com_content.article'              => 'com_content',
+                'com_menus.item'                   => 'menu',
+                'com_categories.categorycom_content' => 'com_content.category',
+            ];
+            $contentType = $formTypeMap[$formName] ?? 'com_content';
+            $language    = $this->getContentLanguage($data);
+            $ogData      = $this->loadOgData($contentType, $id, $language);

            if ($ogData) {
                $form->bind(['mokoog' => (array) $ogData]);
@@ -102,8 +115,9 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
        [$context, $article, $isNew] = array_values($event->getArguments());

        $supportedContexts = [
-            'com_content.article' => 'com_content',
-            'com_menus.item'      => 'menu',
+            'com_content.article'              => 'com_content',
+            'com_menus.item'                   => 'menu',
+            'com_categories.categorycom_content' => 'com_content.category',
        ];

        if (!isset($supportedContexts[$context])) {
@@ -119,6 +133,7 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface

        $contentType = $supportedContexts[$context];
        $contentId   = (int) $article->id;
+        $language    = $this->getContentLanguage($article);

        $input  = $app->getInput();
        $jform  = $input->get('jform', [], 'array');
@@ -128,7 +143,7 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
            return;
        }

-        $this->saveOgData($contentType, $contentId, $ogData);
+        $this->saveOgData($contentType, $contentId, $ogData, $language);
    }

    /**
@@ -143,8 +158,9 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
        [$context, $article] = array_values($event->getArguments());

        $supportedContexts = [
-            'com_content.article' => 'com_content',
-            'com_menus.item'      => 'menu',
+            'com_content.article'              => 'com_content',
+            'com_menus.item'                   => 'menu',
+            'com_categories.categorycom_content' => 'com_content.category',
        ];

        if (!isset($supportedContexts[$context])) {
@@ -165,23 +181,30 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
    }

    /**
-     * Load existing OG data for a content item.
+     * Load existing OG data for a content item, filtered by language.
     *
     * @param   string  $contentType  Content type identifier
     * @param   int     $contentId    Content ID
+     * @param   string  $language     Language tag (e.g. 'en-GB') or '*' for all
     *
     * @return  object|null
     */
-    private function loadOgData(string $contentType, int $contentId): ?object
+    private function loadOgData(string $contentType, int $contentId, string $language = '*'): ?object
    {
        $db    = Factory::getDbo();
        $query = $db->getQuery(true)
-            ->select($db->quoteName(['og_title', 'og_description', 'og_image', 'og_type']))
+            ->select($db->quoteName([
+                'og_title', 'og_description', 'og_image', 'og_type',
+                'seo_title', 'meta_description', 'robots', 'canonical_url',
+            ]))
            ->from($db->quoteName('#__mokoog_tags'))
            ->where($db->quoteName('content_type') . ' = ' . $db->quote($contentType))
-            ->where($db->quoteName('content_id') . ' = ' . $contentId);
+            ->where($db->quoteName('content_id') . ' = ' . $contentId)
+            ->where('(' . $db->quoteName('language') . ' = ' . $db->quote($language)
+                . ' OR ' . $db->quoteName('language') . ' = ' . $db->quote('*') . ')')
+            ->order('CASE WHEN ' . $db->quoteName('language') . ' = ' . $db->quote('*') . ' THEN 1 ELSE 0 END ASC');

-        $db->setQuery($query);
+        $db->setQuery($query, 0, 1);

        return $db->loadObject();
    }
@@ -192,32 +215,46 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
     * @param   string  $contentType  Content type identifier
     * @param   int     $contentId    Content ID
     * @param   array   $ogData       OG field values
+     * @param   string  $language     Language tag (e.g. 'en-GB') or '*' for all
     *
     * @return  void
     */
-    private function saveOgData(string $contentType, int $contentId, array $ogData): void
+    private function saveOgData(string $contentType, int $contentId, array $ogData, string $language = '*'): void
    {
        $db = Factory::getDbo();

-        // Check if record exists
+        // Check if record exists for this content + language
        $query = $db->getQuery(true)
            ->select('id')
            ->from($db->quoteName('#__mokoog_tags'))
            ->where($db->quoteName('content_type') . ' = ' . $db->quote($contentType))
-            ->where($db->quoteName('content_id') . ' = ' . $contentId);
+            ->where($db->quoteName('content_id') . ' = ' . $contentId)
+            ->where($db->quoteName('language') . ' = ' . $db->quote($language));

        $db->setQuery($query);
        $existingId = $db->loadResult();

+        // Robots may come as array from multi-select, join with comma
+        $robots = $ogData['robots'] ?? '';
+
+        if (\is_array($robots)) {
+            $robots = implode(', ', array_filter($robots));
+        }
+
        $record = (object) [
-            'content_type'   => $contentType,
-            'content_id'     => $contentId,
-            'og_title'       => trim($ogData['og_title'] ?? ''),
-            'og_description' => trim($ogData['og_description'] ?? ''),
-            'og_image'       => trim($ogData['og_image'] ?? ''),
-            'og_type'        => trim($ogData['og_type'] ?? 'article'),
-            'published'      => 1,
-            'modified'       => Factory::getDate()->toSql(),
+            'content_type'     => $contentType,
+            'content_id'       => $contentId,
+            'language'         => $language,
+            'og_title'         => trim($ogData['og_title'] ?? ''),
+            'og_description'   => trim($ogData['og_description'] ?? ''),
+            'og_image'         => trim($ogData['og_image'] ?? ''),
+            'og_type'          => trim($ogData['og_type'] ?? 'article'),
+            'seo_title'        => trim($ogData['seo_title'] ?? ''),
+            'meta_description' => trim($ogData['meta_description'] ?? ''),
+            'robots'           => trim($robots),
+            'canonical_url'    => trim($ogData['canonical_url'] ?? ''),
+            'published'        => 1,
+            'modified'         => Factory::getDate()->toSql(),
        ];

        if ($existingId) {
@@ -228,4 +265,24 @@ final class MokoOGContent extends CMSPlugin implements SubscriberInterface
            $db->insertObject('#__mokoog_tags', $record);
        }
    }
+
+    /**
+     * Extract the language tag from content data.
+     *
+     * @param   object|array  $data  Content data from form or article object
+     *
+     * @return  string  Language tag (e.g. 'en-GB') or '*' for all languages
+     */
+    private function getContentLanguage($data): string
+    {
+        $language = '*';
+
+        if (\is_object($data) && isset($data->language)) {
+            $language = $data->language;
+        } elseif (\is_array($data) && isset($data['language'])) {
+            $language = $data['language'];
+        }
+
+        return !empty($language) ? $language : '*';
+    }
 }
@@ -1,4 +1,4 @@
-; MokoOpenGraph - System Plugin Language File
+; MokoJoomOpenGraph - System Plugin Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

@@ -7,6 +7,10 @@ PLG_SYSTEM_MOKOOG_FIELDSET_ADVANCED="Advanced Settings"

 PLG_SYSTEM_MOKOOG_FIELD_SITE_NAME="Site Name"
 PLG_SYSTEM_MOKOOG_FIELD_SITE_NAME_DESC="The og:site_name value. Leave blank to use the Joomla site name."
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_TITLE="Default OG Title"
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_TITLE_DESC="Site-wide fallback title for social sharing. Used when a page has no custom OG title. Leave blank to use the page title."
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_DESCRIPTION="Default OG Description"
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_DESCRIPTION_DESC="Site-wide fallback description for social sharing. Used when a page has no custom OG description and no meta description. Leave blank to auto-generate from page content."
 PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_IMAGE="Default Image"
 PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_IMAGE_DESC="Fallback image used when no article or page image is found."
 PLG_SYSTEM_MOKOOG_FIELD_TWITTER_CARD="Twitter Card Type"
@@ -17,9 +21,19 @@ PLG_SYSTEM_MOKOOG_FIELD_TWITTER_SITE="Twitter @username"
 PLG_SYSTEM_MOKOOG_FIELD_TWITTER_SITE_DESC="Your site's Twitter handle (e.g. @mokoconsulting)."
 PLG_SYSTEM_MOKOOG_FIELD_FB_APP_ID="Facebook App ID"
 PLG_SYSTEM_MOKOOG_FIELD_FB_APP_ID_DESC="Your Facebook App ID for fb:app_id meta tag."
+PLG_SYSTEM_MOKOOG_FIELD_DISCORD_COLOR="Discord Embed Color"
+PLG_SYSTEM_MOKOOG_FIELD_DISCORD_COLOR_DESC="The color of the embed sidebar when shared on Discord. Sets the theme-color meta tag. Leave blank to use Discord defaults."
 PLG_SYSTEM_MOKOOG_FIELD_AUTO_GENERATE="Auto-generate Tags"
 PLG_SYSTEM_MOKOOG_FIELD_AUTO_GENERATE_DESC="Automatically generate OG tags from article content when no custom tags are set."
 PLG_SYSTEM_MOKOOG_FIELD_STRIP_HTML="Strip HTML from Description"
 PLG_SYSTEM_MOKOOG_FIELD_STRIP_HTML_DESC="Remove HTML tags from the auto-generated description."
 PLG_SYSTEM_MOKOOG_FIELD_DESC_LENGTH="Description Length"
 PLG_SYSTEM_MOKOOG_FIELD_DESC_LENGTH_DESC="Maximum character length for the auto-generated og:description."
+PLG_SYSTEM_MOKOOG_FIELD_TELEGRAM_CHANNEL="Telegram Channel"
+PLG_SYSTEM_MOKOOG_FIELD_TELEGRAM_CHANNEL_DESC="Your Telegram channel handle (e.g. @mokoconsulting). Outputs a telegram:channel meta tag for Telegram link previews."
+PLG_SYSTEM_MOKOOG_FIELD_AUTO_RESIZE="Auto-resize Images"
+PLG_SYSTEM_MOKOOG_FIELD_AUTO_RESIZE_DESC="Automatically resize images to 1200x630px (Facebook recommended) using center crop. Generated images are saved to images/mokoog/generated/."
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_ENABLED="Enable JSON-LD"
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_ENABLED_DESC="Output JSON-LD structured data (Article, WebPage) for Google rich results."
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_BREADCRUMBS="JSON-LD Breadcrumbs"
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_BREADCRUMBS_DESC="Output BreadcrumbList JSON-LD schema from Joomla's pathway."
@@ -1,6 +1,6 @@
-; MokoOpenGraph - System Plugin System Language File
+; MokoJoomOpenGraph - System Plugin System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-PLG_SYSTEM_MOKOOG="System - MokoOpenGraph"
+PLG_SYSTEM_MOKOOG="System - MokoJoomOpenGraph"
 PLG_SYSTEM_MOKOOG_DESCRIPTION="Injects Open Graph and Twitter Card meta tags into every page for optimal social media sharing previews."
@@ -1,4 +1,4 @@
-; MokoOpenGraph - System Plugin Language File
+; MokoJoomOpenGraph - System Plugin Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

@@ -7,6 +7,10 @@ PLG_SYSTEM_MOKOOG_FIELDSET_ADVANCED="Advanced Settings"

 PLG_SYSTEM_MOKOOG_FIELD_SITE_NAME="Site Name"
 PLG_SYSTEM_MOKOOG_FIELD_SITE_NAME_DESC="The og:site_name value. Leave blank to use the Joomla site name."
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_TITLE="Default OG Title"
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_TITLE_DESC="Site-wide fallback title for social sharing. Used when a page has no custom OG title. Leave blank to use the page title."
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_DESCRIPTION="Default OG Description"
+PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_DESCRIPTION_DESC="Site-wide fallback description for social sharing. Used when a page has no custom OG description and no meta description. Leave blank to auto-generate from page content."
 PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_IMAGE="Default Image"
 PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_IMAGE_DESC="Fallback image used when no article or page image is found."
 PLG_SYSTEM_MOKOOG_FIELD_TWITTER_CARD="Twitter Card Type"
@@ -17,9 +21,19 @@ PLG_SYSTEM_MOKOOG_FIELD_TWITTER_SITE="Twitter @username"
 PLG_SYSTEM_MOKOOG_FIELD_TWITTER_SITE_DESC="Your site's Twitter handle (e.g. @mokoconsulting)."
 PLG_SYSTEM_MOKOOG_FIELD_FB_APP_ID="Facebook App ID"
 PLG_SYSTEM_MOKOOG_FIELD_FB_APP_ID_DESC="Your Facebook App ID for fb:app_id meta tag."
+PLG_SYSTEM_MOKOOG_FIELD_DISCORD_COLOR="Discord Embed Color"
+PLG_SYSTEM_MOKOOG_FIELD_DISCORD_COLOR_DESC="The color of the embed sidebar when shared on Discord. Sets the theme-color meta tag. Leave blank to use Discord defaults."
 PLG_SYSTEM_MOKOOG_FIELD_AUTO_GENERATE="Auto-generate Tags"
 PLG_SYSTEM_MOKOOG_FIELD_AUTO_GENERATE_DESC="Automatically generate OG tags from article content when no custom tags are set."
 PLG_SYSTEM_MOKOOG_FIELD_STRIP_HTML="Strip HTML from Description"
 PLG_SYSTEM_MOKOOG_FIELD_STRIP_HTML_DESC="Remove HTML tags from the auto-generated description."
 PLG_SYSTEM_MOKOOG_FIELD_DESC_LENGTH="Description Length"
 PLG_SYSTEM_MOKOOG_FIELD_DESC_LENGTH_DESC="Maximum character length for the auto-generated og:description."
+PLG_SYSTEM_MOKOOG_FIELD_TELEGRAM_CHANNEL="Telegram Channel"
+PLG_SYSTEM_MOKOOG_FIELD_TELEGRAM_CHANNEL_DESC="Your Telegram channel handle (e.g. @mokoconsulting). Outputs a telegram:channel meta tag for Telegram link previews."
+PLG_SYSTEM_MOKOOG_FIELD_AUTO_RESIZE="Auto-resize Images"
+PLG_SYSTEM_MOKOOG_FIELD_AUTO_RESIZE_DESC="Automatically resize images to 1200x630px (Facebook recommended) using center crop. Generated images are saved to images/mokoog/generated/."
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_ENABLED="Enable JSON-LD"
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_ENABLED_DESC="Output JSON-LD structured data (Article, WebPage) for Google rich results."
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_BREADCRUMBS="JSON-LD Breadcrumbs"
+PLG_SYSTEM_MOKOOG_FIELD_JSONLD_BREADCRUMBS_DESC="Output BreadcrumbList JSON-LD schema from Joomla's pathway."
@@ -1,6 +1,6 @@
-; MokoOpenGraph - System Plugin System Language File
+; MokoJoomOpenGraph - System Plugin System Language File
 ; Copyright (C) 2026 Moko Consulting. All rights reserved.
 ; License: GPL-3.0-or-later

-PLG_SYSTEM_MOKOOG="System - MokoOpenGraph"
+PLG_SYSTEM_MOKOOG="System - MokoJoomOpenGraph"
 PLG_SYSTEM_MOKOOG_DESCRIPTION="Injects Open Graph and Twitter Card meta tags into every page for optimal social media sharing previews."
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_system_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,14 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_system_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE
 -->
 <extension type="plugin" group="system" method="upgrade">
-    <name>System - MokoOpenGraph</name>
-    <version>01.00.00</version>
+    <name>System - MokoJoomOpenGraph</name>
+    <version>01.00.01-rc</version>
    <creationDate>2026-05-23</creationDate>
    <author>Moko Consulting</author>
    <authorEmail>hello@mokoconsulting.tech</authorEmail>
@@ -41,6 +41,23 @@
                    description="PLG_SYSTEM_MOKOOG_FIELD_SITE_NAME_DESC"
                    default=""
                />
+                <field
+                    name="default_og_title"
+                    type="text"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_TITLE"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_TITLE_DESC"
+                    default=""
+                    filter="string"
+                />
+                <field
+                    name="default_og_description"
+                    type="textarea"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_DESCRIPTION"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_DEFAULT_OG_DESCRIPTION_DESC"
+                    default=""
+                    filter="string"
+                    rows="3"
+                />
                <field
                    name="default_image"
                    type="media"
@@ -74,6 +91,21 @@
                    default=""
                    filter="string"
                />
+                <field
+                    name="telegram_channel"
+                    type="text"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_TELEGRAM_CHANNEL"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_TELEGRAM_CHANNEL_DESC"
+                    default=""
+                    filter="string"
+                />
+                <field
+                    name="discord_color"
+                    type="color"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_DISCORD_COLOR"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_DISCORD_COLOR_DESC"
+                    default=""
+                />
            </fieldset>
            <fieldset name="advanced" label="PLG_SYSTEM_MOKOOG_FIELDSET_ADVANCED">
                <field
@@ -107,6 +139,39 @@
                    min="50"
                    max="300"
                />
+                <field
+                    name="auto_resize"
+                    type="radio"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_AUTO_RESIZE"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_AUTO_RESIZE_DESC"
+                    default="1"
+                    class="btn-group"
+                >
+                    <option value="1">JYES</option>
+                    <option value="0">JNO</option>
+                </field>
+                <field
+                    name="jsonld_enabled"
+                    type="radio"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_JSONLD_ENABLED"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_JSONLD_ENABLED_DESC"
+                    default="1"
+                    class="btn-group"
+                >
+                    <option value="1">JYES</option>
+                    <option value="0">JNO</option>
+                </field>
+                <field
+                    name="jsonld_breadcrumbs"
+                    type="radio"
+                    label="PLG_SYSTEM_MOKOOG_FIELD_JSONLD_BREADCRUMBS"
+                    description="PLG_SYSTEM_MOKOOG_FIELD_JSONLD_BREADCRUMBS_DESC"
+                    default="1"
+                    class="btn-group"
+                >
+                    <option value="1">JYES</option>
+                    <option value="0">JNO</option>
+                </field>
            </fieldset>
        </fields>
    </config>
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_system_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @subpackage  plg_system_mokoog
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
@@ -17,6 +17,8 @@ use Joomla\CMS\Plugin\CMSPlugin;
 use Joomla\CMS\Uri\Uri;
 use Joomla\Event\Event;
 use Joomla\Event\SubscriberInterface;
+use Joomla\Plugin\System\MokoOG\Helper\ImageHelper;
+use Joomla\Plugin\System\MokoOG\Helper\JsonLdBuilder;

 final class MokoOG extends CMSPlugin implements SubscriberInterface
 {
@@ -67,9 +69,29 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
        // Try to load custom OG data from the database
        $ogData = $this->loadOgData($option, $view, $id);

-        // Build tag values — custom overrides auto-generated
-        $title       = $ogData->og_title ?: $doc->getTitle();
-        $description = $ogData->og_description ?: $this->buildDescription($doc);
+        // For category views, also try category-level OG data as fallback
+        if ($option === 'com_content' && $view === 'category' && $id > 0) {
+            $catOg = $this->loadOgDataByType('com_content.category', $id);
+
+            if ($catOg) {
+                // Merge: category fills any gaps in the content-level data
+                foreach (['og_title', 'og_description', 'og_image', 'og_type', 'seo_title', 'meta_description', 'robots', 'canonical_url'] as $field) {
+                    if (empty($ogData->$field) && !empty($catOg->$field)) {
+                        $ogData->$field = $catOg->$field;
+                    }
+                }
+            }
+        }
+
+        // --- SEO meta tags (set first, before OG) ---
+        $this->applySeoTags($doc, $ogData);
+
+        // Build tag values — custom OG data → site-wide defaults → auto-generated
+        $defaultTitle = $this->params->get('default_og_title', '');
+        $defaultDesc  = $this->params->get('default_og_description', '');
+
+        $title       = $ogData->og_title ?: ($doc->getTitle() ?: $defaultTitle);
+        $description = $ogData->og_description ?: ($this->buildDescription($doc) ?: $defaultDesc);
        $image       = $ogData->og_image ?: $this->findImage($option, $view, $id);
        $url         = Uri::getInstance()->toString();
        $siteName    = $this->params->get('og_site_name', $app->get('sitename', ''));
@@ -85,8 +107,17 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
        if ($image) {
            $imageUrl = $this->resolveImageUrl($image);
            $doc->setMetaData('og:image', $imageUrl, 'property');
+
+            // Image dimensions help Facebook, LinkedIn, and Discord render previews faster
+            $doc->setMetaData('og:image:width', '1200', 'property');
+            $doc->setMetaData('og:image:height', '630', 'property');
        }

+        // og:locale from current language
+        $langTag   = Factory::getLanguage()->getTag();
+        $ogLocale  = str_replace('-', '_', $langTag);
+        $doc->setMetaData('og:locale', $ogLocale, 'property');
+
        // Facebook App ID
        $fbAppId = $this->params->get('fb_app_id', '');

@@ -109,6 +140,107 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
        if ($twitterSite) {
            $doc->setMetaData('twitter:site', $twitterSite);
        }
+
+        // Telegram channel tag
+        $telegramChannel = $this->params->get('telegram_channel', '');
+
+        if ($telegramChannel) {
+            $doc->setMetaData('telegram:channel', $telegramChannel);
+        }
+
+        // Discord embed color (theme-color meta tag)
+        $discordColor = $this->params->get('discord_color', '');
+
+        if ($discordColor) {
+            $doc->setMetaData('theme-color', $discordColor);
+        }
+
+        // LinkedIn article tags
+        if ($option === 'com_content' && $view === 'article' && $id > 0) {
+            $doc->setMetaData('article:published_time', $this->getArticleDate($id, 'publish_up'), 'property');
+            $doc->setMetaData('article:modified_time', $this->getArticleDate($id, 'modified'), 'property');
+
+            $author = $this->getArticleAuthor($id);
+
+            if ($author) {
+                $doc->setMetaData('article:author', $author, 'property');
+            }
+        }
+
+        // Fire event so third-party plugins can add custom OG/social tags
+        $eventData = [
+            'subject' => $doc,
+            'title'   => $title,
+            'description' => $description,
+            'image'   => $image ? $this->resolveImageUrl($image) : '',
+            'url'     => $url,
+            'type'    => $type,
+            'option'  => $option,
+            'view'    => $view,
+            'id'      => $id,
+        ];
+        $app->getDispatcher()->dispatch('onMokoOGAfterRender', new Event('onMokoOGAfterRender', $eventData));
+
+        // JSON-LD structured data
+        if ($this->params->get('jsonld_enabled', 1)) {
+            $imageUrl  = $image ? $this->resolveImageUrl($image) : '';
+
+            if ($option === 'com_content' && $view === 'article' && $id > 0) {
+                $schema = JsonLdBuilder::buildArticle($id, $title, $description, $imageUrl);
+            } else {
+                $schema = JsonLdBuilder::buildWebPage($title, $description);
+            }
+
+            if ($schema) {
+                $doc->addCustomTag(JsonLdBuilder::toScriptTag($schema));
+            }
+
+            if ($this->params->get('jsonld_breadcrumbs', 1)) {
+                $breadcrumbs = JsonLdBuilder::buildBreadcrumbs();
+
+                if ($breadcrumbs) {
+                    $doc->addCustomTag(JsonLdBuilder::toScriptTag($breadcrumbs));
+                }
+            }
+        }
+    }
+
+    /**
+     * Apply SEO meta tags (title, description, robots, canonical) to the document.
+     *
+     * @param   \Joomla\CMS\Document\HtmlDocument  $doc     The document
+     * @param   object                              $ogData  The loaded OG/SEO data
+     *
+     * @return  void
+     */
+    private function applySeoTags($doc, object $ogData): void
+    {
+        // Custom SEO title overrides the page <title>
+        if (!empty($ogData->seo_title)) {
+            $doc->setTitle($ogData->seo_title);
+        }
+
+        // Custom meta description
+        if (!empty($ogData->meta_description)) {
+            $doc->setDescription($ogData->meta_description);
+        }
+
+        // Robots directive
+        if (!empty($ogData->robots)) {
+            $doc->setMetaData('robots', $ogData->robots);
+        }
+
+        // Canonical URL
+        if (!empty($ogData->canonical_url)) {
+            // Remove any existing canonical link first
+            foreach ($doc->_links as $link => $attribs) {
+                if (isset($attribs['relation']) && $attribs['relation'] === 'canonical') {
+                    unset($doc->_links[$link]);
+                }
+            }
+
+            $doc->addHeadLink($ogData->canonical_url, 'canonical');
+        }
    }

    /**
@@ -123,10 +255,14 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
    private function loadOgData(string $option, string $view, int $id): object
    {
        $empty = (object) [
-            'og_title'       => '',
-            'og_description' => '',
-            'og_image'       => '',
-            'og_type'        => '',
+            'og_title'         => '',
+            'og_description'   => '',
+            'og_image'         => '',
+            'og_type'          => '',
+            'seo_title'        => '',
+            'meta_description' => '',
+            'robots'           => '',
+            'canonical_url'    => '',
        ];

        if (!$id) {
@@ -146,11 +282,37 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
            ->from($db->quoteName('#__mokoog_tags'))
            ->where($db->quoteName('content_type') . ' = ' . $db->quote($option))
            ->where($db->quoteName('content_id') . ' = ' . (int) $id)
+            ->where($db->quoteName('published') . ' = 1')
+            ->where('(' . $db->quoteName('language') . ' = ' . $db->quote(Factory::getLanguage()->getTag())
+                . ' OR ' . $db->quoteName('language') . ' = ' . $db->quote('*') . ')')
+            ->order('CASE WHEN ' . $db->quoteName('language') . ' = ' . $db->quote('*') . ' THEN 1 ELSE 0 END ASC');
+
+        $db->setQuery($query, 0, 1);
+
+        return $db->loadObject() ?: $empty;
+    }
+
+    /**
+     * Load OG data by content type and ID.
+     *
+     * @param   string  $contentType  Content type identifier
+     * @param   int     $contentId    Content ID
+     *
+     * @return  object|null
+     */
+    private function loadOgDataByType(string $contentType, int $contentId): ?object
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select('*')
+            ->from($db->quoteName('#__mokoog_tags'))
+            ->where($db->quoteName('content_type') . ' = ' . $db->quote($contentType))
+            ->where($db->quoteName('content_id') . ' = ' . $contentId)
            ->where($db->quoteName('published') . ' = 1');

        $db->setQuery($query);

-        return $db->loadObject() ?: $empty;
+        return $db->loadObject();
    }

    /**
@@ -237,13 +399,33 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
                    return $imagesData['image_intro'];
                }
            }
+
+            // Fallback: check the article's category for an image
+            if ($view === 'article') {
+                $catQuery = $db->getQuery(true)
+                    ->select($db->quoteName('cat.params'))
+                    ->from($db->quoteName('#__categories', 'cat'))
+                    ->join('INNER', $db->quoteName('#__content', 'a') . ' ON ' . $db->quoteName('a.catid') . ' = ' . $db->quoteName('cat.id'))
+                    ->where($db->quoteName('a.id') . ' = ' . (int) $id);
+
+                $db->setQuery($catQuery);
+                $catParams = $db->loadResult();
+
+                if ($catParams) {
+                    $catData = json_decode($catParams, true);
+
+                    if (!empty($catData['image'])) {
+                        return $catData['image'];
+                    }
+                }
+            }
        }

        return $this->params->get('default_image', '');
    }

    /**
-     * Resolve a relative image path to a full URL.
+     * Resolve a relative image path to a full URL, resizing for OG if needed.
     *
     * @param   string  $image  Image path
     *
@@ -255,6 +437,54 @@ final class MokoOG extends CMSPlugin implements SubscriberInterface
            return $image;
        }

+        // Auto-resize to OG recommended dimensions if enabled
+        if ($this->params->get('auto_resize', 1)) {
+            $image = ImageHelper::resize($image);
+        }
+
        return rtrim(Uri::root(), '/') . '/' . ltrim($image, '/');
    }
+
+    /**
+     * Get a date field from an article.
+     *
+     * @param   int     $id     Article ID
+     * @param   string  $field  Date field name (publish_up, modified, created)
+     *
+     * @return  string  ISO 8601 date string
+     */
+    private function getArticleDate(int $id, string $field): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName($field))
+            ->from($db->quoteName('#__content'))
+            ->where($db->quoteName('id') . ' = ' . $id);
+
+        $db->setQuery($query);
+        $date = $db->loadResult();
+
+        return $date ?: '';
+    }
+
+    /**
+     * Get the author name for an article.
+     *
+     * @param   int  $id  Article ID
+     *
+     * @return  string
+     */
+    private function getArticleAuthor(int $id): string
+    {
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName('u.name'))
+            ->from($db->quoteName('#__content', 'a'))
+            ->join('LEFT', $db->quoteName('#__users', 'u') . ' ON ' . $db->quoteName('u.id') . ' = ' . $db->quoteName('a.created_by'))
+            ->where($db->quoteName('a.id') . ' = ' . $id);
+
+        $db->setQuery($query);
+
+        return $db->loadResult() ?: '';
+    }
 }
@@ -0,0 +1,160 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_system_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Plugin\System\MokoOG\Helper;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Filesystem\Folder;
+
+class ImageGenerator
+{
+    private const WIDTH = 1200;
+    private const HEIGHT = 630;
+    private const OUTPUT_DIR = 'images/mokoog/generated';
+
+    /**
+     * Generate an OG image with title text overlaid on a template background.
+     *
+     * @param   string  $title           Article title to overlay
+     * @param   string  $templateImage   Path to template/background image relative to JPATH_ROOT
+     * @param   string  $fontFile        Absolute path to TTF font file
+     * @param   int     $fontSize        Font size in points (default 42)
+     * @param   array   $fontColor       RGB array [r, g, b] (default white)
+     * @param   int     $quality         JPEG quality (default 90)
+     *
+     * @return  string  Path to generated image relative to JPATH_ROOT, or empty on failure
+     */
+    public static function generate(
+        string $title,
+        string $templateImage,
+        string $fontFile = '',
+        int $fontSize = 42,
+        array $fontColor = [255, 255, 255],
+        int $quality = 90
+    ): string {
+        $templateAbs = JPATH_ROOT . '/' . ltrim($templateImage, '/');
+
+        if (!is_file($templateAbs)) {
+            return '';
+        }
+
+        if (!$fontFile || !is_file($fontFile)) {
+            return '';
+        }
+
+        $outputDir = JPATH_ROOT . '/' . self::OUTPUT_DIR;
+
+        if (!is_dir($outputDir)) {
+            Folder::create($outputDir);
+        }
+
+        $hash       = md5($title . $templateImage . $fontSize);
+        $outputName = 'overlay_' . $hash . '.jpg';
+        $outputPath = $outputDir . '/' . $outputName;
+        $outputRel  = self::OUTPUT_DIR . '/' . $outputName;
+
+        // Skip if already generated
+        if (is_file($outputPath)) {
+            return $outputRel;
+        }
+
+        // Load template image
+        $imageInfo = @getimagesize($templateAbs);
+
+        if (!$imageInfo) {
+            return '';
+        }
+
+        $source = match ($imageInfo[2]) {
+            IMAGETYPE_JPEG => @imagecreatefromjpeg($templateAbs),
+            IMAGETYPE_PNG  => @imagecreatefrompng($templateAbs),
+            IMAGETYPE_WEBP => @imagecreatefromwebp($templateAbs),
+            default        => false,
+        };
+
+        if (!$source) {
+            return '';
+        }
+
+        // Create output canvas at target dimensions
+        $canvas = imagecreatetruecolor(self::WIDTH, self::HEIGHT);
+
+        imagecopyresampled(
+            $canvas,
+            $source,
+            0, 0, 0, 0,
+            self::WIDTH, self::HEIGHT,
+            $imageInfo[0], $imageInfo[1]
+        );
+
+        imagedestroy($source);
+
+        // Semi-transparent overlay for text readability
+        $overlay = imagecolorallocatealpha($canvas, 0, 0, 0, 64);
+        imagefilledrectangle($canvas, 0, (int) (self::HEIGHT * 0.55), self::WIDTH, self::HEIGHT, $overlay);
+
+        // Render title text with word wrapping
+        $textColor = imagecolorallocate($canvas, $fontColor[0], $fontColor[1], $fontColor[2]);
+        $wrappedTitle = self::wrapText($title, $fontFile, $fontSize, (int) (self::WIDTH * 0.85));
+        $textX = (int) (self::WIDTH * 0.075);
+        $textY = (int) (self::HEIGHT * 0.72);
+
+        imagettftext($canvas, $fontSize, 0, $textX, $textY, $textColor, $fontFile, $wrappedTitle);
+
+        // Save
+        imagejpeg($canvas, $outputPath, $quality);
+        imagedestroy($canvas);
+
+        return $outputRel;
+    }
+
+    /**
+     * Wrap text to fit within a maximum pixel width.
+     *
+     * @param   string  $text      Text to wrap
+     * @param   string  $fontFile  Path to TTF font
+     * @param   int     $fontSize  Font size in points
+     * @param   int     $maxWidth  Maximum width in pixels
+     *
+     * @return  string  Wrapped text with newlines
+     */
+    private static function wrapText(string $text, string $fontFile, int $fontSize, int $maxWidth): string
+    {
+        $words  = explode(' ', $text);
+        $lines  = [];
+        $line   = '';
+
+        foreach ($words as $word) {
+            $testLine = $line ? $line . ' ' . $word : $word;
+            $bbox     = imagettfbbox($fontSize, 0, $fontFile, $testLine);
+            $lineWidth = abs($bbox[4] - $bbox[0]);
+
+            if ($lineWidth > $maxWidth && $line !== '') {
+                $lines[] = $line;
+                $line    = $word;
+            } else {
+                $line = $testLine;
+            }
+        }
+
+        if ($line !== '') {
+            $lines[] = $line;
+        }
+
+        // Limit to 3 lines, truncate last line if needed
+        if (\count($lines) > 3) {
+            $lines = \array_slice($lines, 0, 3);
+            $lines[2] = mb_substr($lines[2], 0, -3) . '...';
+        }
+
+        return implode("\n", $lines);
+    }
+}
@@ -0,0 +1,222 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_system_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Plugin\System\MokoOG\Helper;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Filesystem\File;
+use Joomla\CMS\Filesystem\Folder;
+
+class ImageHelper
+{
+    /**
+     * Target width for OG images (Facebook recommended).
+     */
+    private const TARGET_WIDTH = 1200;
+
+    /**
+     * Target height for OG images (Facebook recommended).
+     */
+    private const TARGET_HEIGHT = 630;
+
+    /**
+     * JPEG quality for generated images.
+     */
+    private const JPEG_QUALITY = 85;
+
+    /**
+     * Output directory relative to JPATH_ROOT.
+     */
+    private const OUTPUT_DIR = 'images/mokoog/generated';
+
+    /**
+     * Resize an image to OG-optimized dimensions if needed.
+     *
+     * Returns the path to the resized image relative to JPATH_ROOT,
+     * or the original path if no resize was needed or possible.
+     *
+     * @param   string  $imagePath    Image path relative to JPATH_ROOT
+     * @param   int     $targetWidth  Target width (default 1200)
+     * @param   int     $targetHeight Target height (default 630)
+     * @param   int     $quality      JPEG quality 1-100 (default 85)
+     *
+     * @return  string  Path to the output image (relative to JPATH_ROOT)
+     */
+    public static function resize(
+        string $imagePath,
+        int $targetWidth = self::TARGET_WIDTH,
+        int $targetHeight = self::TARGET_HEIGHT,
+        int $quality = self::JPEG_QUALITY
+    ): string {
+        // Resolve absolute path
+        $absPath = JPATH_ROOT . '/' . ltrim($imagePath, '/');
+
+        if (!is_file($absPath)) {
+            return $imagePath;
+        }
+
+        $imageInfo = @getimagesize($absPath);
+
+        if (!$imageInfo) {
+            return $imagePath;
+        }
+
+        [$origWidth, $origHeight, $type] = $imageInfo;
+
+        // Skip if already at or below target size
+        if ($origWidth <= $targetWidth && $origHeight <= $targetHeight) {
+            return $imagePath;
+        }
+
+        // Ensure output directory exists
+        $outputDir = JPATH_ROOT . '/' . self::OUTPUT_DIR;
+
+        if (!is_dir($outputDir)) {
+            Folder::create($outputDir);
+        }
+
+        // Generate output filename based on source hash + dimensions
+        $hash       = md5($imagePath . $targetWidth . $targetHeight);
+        $outputName = $hash . '.jpg';
+        $outputPath = $outputDir . '/' . $outputName;
+        $outputRel  = self::OUTPUT_DIR . '/' . $outputName;
+
+        // Skip if already generated
+        if (is_file($outputPath) && filemtime($outputPath) >= filemtime($absPath)) {
+            return $outputRel;
+        }
+
+        // Load source image
+        $source = self::loadImage($absPath, $type);
+
+        if (!$source) {
+            return $imagePath;
+        }
+
+        // Calculate crop dimensions (center crop to target aspect ratio)
+        $targetRatio = $targetWidth / $targetHeight;
+        $sourceRatio = $origWidth / $origHeight;
+
+        if ($sourceRatio > $targetRatio) {
+            // Source is wider — crop sides
+            $cropHeight = $origHeight;
+            $cropWidth  = (int) round($origHeight * $targetRatio);
+            $cropX      = (int) round(($origWidth - $cropWidth) / 2);
+            $cropY      = 0;
+        } else {
+            // Source is taller — crop top/bottom
+            $cropWidth  = $origWidth;
+            $cropHeight = (int) round($origWidth / $targetRatio);
+            $cropX      = 0;
+            $cropY      = (int) round(($origHeight - $cropHeight) / 2);
+        }
+
+        // Create output canvas and resample
+        $output = imagecreatetruecolor($targetWidth, $targetHeight);
+
+        imagecopyresampled(
+            $output,
+            $source,
+            0,
+            0,
+            $cropX,
+            $cropY,
+            $targetWidth,
+            $targetHeight,
+            $cropWidth,
+            $cropHeight
+        );
+
+        // Save as JPEG
+        imagejpeg($output, $outputPath, $quality);
+
+        imagedestroy($source);
+        imagedestroy($output);
+
+        return $outputRel;
+    }
+
+    /**
+     * Remove a generated image file.
+     *
+     * @param   string  $generatedPath  Path relative to JPATH_ROOT
+     *
+     * @return  void
+     */
+    public static function cleanup(string $generatedPath): void
+    {
+        if (empty($generatedPath) || !str_starts_with($generatedPath, self::OUTPUT_DIR)) {
+            return;
+        }
+
+        $absPath = JPATH_ROOT . '/' . $generatedPath;
+
+        if (is_file($absPath)) {
+            File::delete($absPath);
+        }
+    }
+
+    /**
+     * Check if an image meets minimum OG size requirements.
+     *
+     * @param   string  $imagePath  Image path relative to JPATH_ROOT
+     *
+     * @return  array{valid: bool, width: int, height: int, message: string}
+     */
+    public static function validate(string $imagePath): array
+    {
+        $absPath = JPATH_ROOT . '/' . ltrim($imagePath, '/');
+
+        if (!is_file($absPath)) {
+            return ['valid' => false, 'width' => 0, 'height' => 0, 'message' => 'File not found'];
+        }
+
+        $imageInfo = @getimagesize($absPath);
+
+        if (!$imageInfo) {
+            return ['valid' => false, 'width' => 0, 'height' => 0, 'message' => 'Not a valid image'];
+        }
+
+        [$width, $height] = $imageInfo;
+
+        // Facebook minimum: 200x200, recommended: 1200x630
+        // WhatsApp minimum: 300x200
+        if ($width < 200 || $height < 200) {
+            return [
+                'valid'   => false,
+                'width'   => $width,
+                'height'  => $height,
+                'message' => "Image too small ({$width}x{$height}). Minimum: 200x200px.",
+            ];
+        }
+
+        return ['valid' => true, 'width' => $width, 'height' => $height, 'message' => 'OK'];
+    }
+
+    /**
+     * Load an image resource from a file.
+     *
+     * @param   string  $path  Absolute file path
+     * @param   int     $type  IMAGETYPE_* constant
+     *
+     * @return  \GdImage|false
+     */
+    private static function loadImage(string $path, int $type)
+    {
+        return match ($type) {
+            IMAGETYPE_JPEG => @imagecreatefromjpeg($path),
+            IMAGETYPE_PNG  => @imagecreatefrompng($path),
+            IMAGETYPE_GIF  => @imagecreatefromgif($path),
+            IMAGETYPE_WEBP => @imagecreatefromwebp($path),
+            default        => false,
+        };
+    }
+}
@@ -0,0 +1,171 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_system_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Plugin\System\MokoOG\Helper;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\CMS\Uri\Uri;
+
+class JsonLdBuilder
+{
+    /**
+     * Build Article schema for a com_content article.
+     *
+     * @param   int     $articleId  Article ID
+     * @param   string  $title      Page title
+     * @param   string  $description  Page description
+     * @param   string  $image      Image URL (absolute)
+     *
+     * @return  array|null
+     */
+    public static function buildArticle(int $articleId, string $title, string $description, string $image): ?array
+    {
+        if ($articleId <= 0) {
+            return null;
+        }
+
+        $db    = Factory::getDbo();
+        $query = $db->getQuery(true)
+            ->select($db->quoteName([
+                'a.created', 'a.modified', 'a.publish_up',
+                'u.name',
+            ]))
+            ->from($db->quoteName('#__content', 'a'))
+            ->join('LEFT', $db->quoteName('#__users', 'u') . ' ON ' . $db->quoteName('u.id') . ' = ' . $db->quoteName('a.created_by'))
+            ->where($db->quoteName('a.id') . ' = ' . $articleId);
+
+        $db->setQuery($query);
+        $article = $db->loadObject();
+
+        if (!$article) {
+            return null;
+        }
+
+        $schema = [
+            '@context'      => 'https://schema.org',
+            '@type'         => 'Article',
+            'headline'      => $title,
+            'description'   => $description,
+            'url'           => Uri::getInstance()->toString(),
+            'datePublished' => $article->publish_up ?: $article->created,
+            'dateModified'  => $article->modified ?: $article->created,
+        ];
+
+        if (!empty($article->name)) {
+            $schema['author'] = [
+                '@type' => 'Person',
+                'name'  => $article->name,
+            ];
+        }
+
+        if (!empty($image)) {
+            $schema['image'] = $image;
+        }
+
+        return $schema;
+    }
+
+    /**
+     * Build WebPage schema for non-article pages.
+     *
+     * @param   string  $title        Page title
+     * @param   string  $description  Page description
+     *
+     * @return  array
+     */
+    public static function buildWebPage(string $title, string $description): array
+    {
+        return [
+            '@context'    => 'https://schema.org',
+            '@type'       => 'WebPage',
+            'name'        => $title,
+            'description' => $description,
+            'url'         => Uri::getInstance()->toString(),
+        ];
+    }
+
+    /**
+     * Build BreadcrumbList schema from Joomla's pathway.
+     *
+     * @return  array|null
+     */
+    public static function buildBreadcrumbs(): ?array
+    {
+        $app     = Factory::getApplication();
+        $pathway = $app->getPathway();
+        $items   = $pathway->getPathway();
+
+        if (empty($items)) {
+            return null;
+        }
+
+        $listItems = [];
+        $position  = 1;
+
+        foreach ($items as $item) {
+            $url = $item->link;
+
+            if ($url && !str_starts_with($url, 'http')) {
+                $url = rtrim(Uri::root(), '/') . '/' . ltrim($url, '/');
+            }
+
+            $listItems[] = [
+                '@type'    => 'ListItem',
+                'position' => $position,
+                'name'     => $item->name,
+                'item'     => $url ?: Uri::getInstance()->toString(),
+            ];
+
+            $position++;
+        }
+
+        return [
+            '@context'        => 'https://schema.org',
+            '@type'           => 'BreadcrumbList',
+            'itemListElement' => $listItems,
+        ];
+    }
+
+    /**
+     * Build Organization schema from site configuration.
+     *
+     * @param   string  $siteName  Site name
+     *
+     * @return  array
+     */
+    public static function buildOrganization(string $siteName): array
+    {
+        return [
+            '@context' => 'https://schema.org',
+            '@type'    => 'Organization',
+            'name'     => $siteName,
+            'url'      => Uri::root(),
+        ];
+    }
+
+    /**
+     * Encode a schema array to a JSON-LD script tag string.
+     *
+     * @param   array  $schema  Schema data
+     *
+     * @return  string
+     */
+    public static function toScriptTag(array $schema): string
+    {
+        $json = json_encode($schema, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
+
+        // Escape </ sequences to prevent XSS via </script> in content data
+        $json = str_replace('</', '<\/', $json);
+
+        return '<script type="application/ld+json">' . $json . '</script>';
+    }
+}
@@ -0,0 +1,5 @@
+; MokoJoomOpenGraph - Web Services Plugin Language File
+; Copyright (C) 2026 Moko Consulting. All rights reserved.
+; License: GPL-3.0-or-later
+
+PLG_WEBSERVICES_MOKOOG="Web Services - MokoJoomOpenGraph"
@@ -0,0 +1,6 @@
+; MokoJoomOpenGraph - Web Services Plugin System Language File
+; Copyright (C) 2026 Moko Consulting. All rights reserved.
+; License: GPL-3.0-or-later
+
+PLG_WEBSERVICES_MOKOOG="Web Services - MokoJoomOpenGraph"
+PLG_WEBSERVICES_MOKOOG_DESCRIPTION="Exposes MokoJoomOpenGraph OG tag data via Joomla's REST API at /api/index.php/v1/mokoog/tags."
@@ -0,0 +1,5 @@
+; MokoJoomOpenGraph - Web Services Plugin Language File
+; Copyright (C) 2026 Moko Consulting. All rights reserved.
+; License: GPL-3.0-or-later
+
+PLG_WEBSERVICES_MOKOOG="Web Services - MokoJoomOpenGraph"
@@ -0,0 +1,6 @@
+; MokoJoomOpenGraph - Web Services Plugin System Language File
+; Copyright (C) 2026 Moko Consulting. All rights reserved.
+; License: GPL-3.0-or-later
+
+PLG_WEBSERVICES_MOKOOG="Web Services - MokoJoomOpenGraph"
+PLG_WEBSERVICES_MOKOOG_DESCRIPTION="Exposes MokoJoomOpenGraph OG tag data via Joomla's REST API at /api/index.php/v1/mokoog/tags."
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_webservices_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ *
+ * Legacy entry point — not executed under DI container.
+ */
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Plugin\CMSPlugin;
+
+class PlgWebservicesMokoog extends CMSPlugin
+{
+}
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_webservices_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ -->
+<extension type="plugin" group="webservices" method="upgrade">
+    <name>Web Services - MokoJoomOpenGraph</name>
+    <version>01.00.01-rc</version>
+    <creationDate>2026-05-23</creationDate>
+    <author>Moko Consulting</author>
+    <authorEmail>hello@mokoconsulting.tech</authorEmail>
+    <authorUrl>https://mokoconsulting.tech</authorUrl>
+    <copyright>Copyright (C) 2026 Moko Consulting. All rights reserved.</copyright>
+    <license>GPL-3.0-or-later</license>
+    <description>PLG_WEBSERVICES_MOKOOG_DESCRIPTION</description>
+
+    <namespace path="src">Joomla\Plugin\WebServices\MokoOG</namespace>
+
+    <files>
+        <filename plugin="mokoog">mokoog.php</filename>
+        <folder>src</folder>
+        <folder>services</folder>
+        <folder>language</folder>
+    </files>
+
+    <languages>
+        <language tag="en-GB">language/en-GB/plg_webservices_mokoog.ini</language>
+        <language tag="en-GB">language/en-GB/plg_webservices_mokoog.sys.ini</language>
+    </languages>
+</extension>
@@ -0,0 +1,44 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_webservices_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Extension\PluginInterface;
+use Joomla\CMS\Factory;
+use Joomla\CMS\Plugin\PluginHelper;
+use Joomla\DI\Container;
+use Joomla\DI\ServiceProviderInterface;
+use Joomla\Event\DispatcherInterface;
+use Joomla\Plugin\WebServices\MokoOG\Extension\MokoOGWebServices;
+
+return new class () implements ServiceProviderInterface {
+    /**
+     * Register the service provider.
+     *
+     * @param   Container  $container  The DI container
+     *
+     * @return  void
+     */
+    public function register(Container $container): void
+    {
+        $container->set(
+            PluginInterface::class,
+            function (Container $container) {
+                $plugin = new MokoOGWebServices(
+                    $container->get(DispatcherInterface::class),
+                    (array) PluginHelper::getPlugin('webservices', 'mokoog')
+                );
+                $plugin->setApplication(Factory::getApplication());
+
+                return $plugin;
+            }
+        );
+    }
+};
@@ -0,0 +1,81 @@
+<?php
+
+/**
+ * @package     MokoJoomOpenGraph
+ * @subpackage  plg_webservices_mokoog
+ * @author      Moko Consulting <hello@mokoconsulting.tech>
+ * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
+ * @license     GNU General Public License version 3 or later; see LICENSE
+ */
+
+namespace Joomla\Plugin\WebServices\MokoOG\Extension;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Plugin\CMSPlugin;
+use Joomla\CMS\Router\ApiRouter;
+use Joomla\Event\Event;
+use Joomla\Event\SubscriberInterface;
+use Joomla\Router\Route;
+
+final class MokoOGWebServices extends CMSPlugin implements SubscriberInterface
+{
+    /**
+     * @var bool
+     */
+    protected $autoloadLanguage = true;
+
+    /**
+     * Returns the events this plugin subscribes to.
+     *
+     * @return  array<string, string>
+     */
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            'onBeforeApiRoute' => 'onBeforeApiRoute',
+        ];
+    }
+
+    /**
+     * Register API routes for MokoJoomOpenGraph.
+     *
+     * Endpoints:
+     *   GET    /api/index.php/v1/mokoog/tags        - List all OG tags
+     *   GET    /api/index.php/v1/mokoog/tags/:id     - Get single OG tag
+     *   POST   /api/index.php/v1/mokoog/tags        - Create OG tag
+     *   PATCH  /api/index.php/v1/mokoog/tags/:id     - Update OG tag
+     *   DELETE /api/index.php/v1/mokoog/tags/:id     - Delete OG tag
+     *
+     * @param   Event  $event  The event object
+     *
+     * @return  void
+     */
+    public function onBeforeApiRoute(Event $event): void
+    {
+        [$router] = array_values($event->getArguments());
+
+        $defaults = [
+            'component' => 'com_mokoog',
+            'public'    => false,
+        ];
+
+        // CRUD routes for OG tags
+        $router->createCRUDRoutes(
+            'v1/mokoog/tags',
+            'tags',
+            $defaults
+        );
+
+        // GET by content type + content ID (lookup endpoint)
+        $router->addRoute(
+            new Route(
+                ['GET'],
+                'v1/mokoog/lookup/:content_type/:content_id',
+                'tags.lookup',
+                ['content_type' => '[a-z_.]+', 'content_id' => '(\d+)'],
+                $defaults
+            )
+        );
+    }
+}
@@ -1,14 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE
 -->
 <extension type="package" method="upgrade">
-    <name>MokoOpenGraph</name>
+    <name>Package - MokoJoomOpenGraph</name>
    <packagename>mokoog</packagename>
-    <version>01.00.00</version>
+    <version>01.00.01-rc</version>
    <creationDate>2026-05-23</creationDate>
    <author>Moko Consulting</author>
    <authorEmail>hello@mokoconsulting.tech</authorEmail>
@@ -23,6 +23,7 @@
        <file type="component" id="com_mokoog">com_mokoog.zip</file>
        <file type="plugin" id="mokoog" group="system">plg_system_mokoog.zip</file>
        <file type="plugin" id="mokoog" group="content">plg_content_mokoog.zip</file>
+        <file type="plugin" id="mokoog" group="webservices">plg_webservices_mokoog.zip</file>
    </files>

    <languages>
@@ -30,6 +31,6 @@
    </languages>

    <updateservers>
-        <server type="extension" name="MokoOpenGraph Updates">https://git.mokoconsulting.tech/MokoConsulting/MokoOpenGraph/raw/branch/main/updates.xml</server>
+        <server type="extension" name="MokoJoomOpenGraph Updates">https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/raw/branch/main/updates.xml</server>
    </updateservers>
 </extension>
@@ -1,7 +1,7 @@
 <?php

 /**
- * @package     MokoOpenGraph
+ * @package     MokoJoomOpenGraph
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE
@@ -73,6 +73,28 @@ class Pkg_MokoOGInstallerScript

            $db->setQuery($query);
            $db->execute();
+
+            // Enable the content plugin automatically
+            $query = $db->getQuery(true)
+                ->update($db->quoteName('#__extensions'))
+                ->set($db->quoteName('enabled') . ' = 1')
+                ->where($db->quoteName('type') . ' = ' . $db->quote('plugin'))
+                ->where($db->quoteName('folder') . ' = ' . $db->quote('content'))
+                ->where($db->quoteName('element') . ' = ' . $db->quote('mokoog'));
+
+            $db->setQuery($query);
+            $db->execute();
+
+            // Enable the webservices plugin automatically
+            $query = $db->getQuery(true)
+                ->update($db->quoteName('#__extensions'))
+                ->set($db->quoteName('enabled') . ' = 1')
+                ->where($db->quoteName('type') . ' = ' . $db->quote('plugin'))
+                ->where($db->quoteName('folder') . ' = ' . $db->quote('webservices'))
+                ->where($db->quoteName('element') . ' = ' . $db->quote('mokoog'));
+
+            $db->setQuery($query);
+            $db->execute();
        }
    }
 }
@@ -1,4 +1,27 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ SPDX-License-Identifier: GPL-3.0-or-later
+ VERSION: 01.00.01-dev
+ -->
+
 <updates>
-    <!-- Managed by CI/CD pipeline — do not edit manually -->
+  <update>
+    <name>Package - MokoJoomOpenGraph</name>
+    <description>Package - MokoJoomOpenGraph development build.</description>
+    <element>pkg_mokoog</element>
+    <type>package</type>
+    <client>site</client>
+    <version>01.00.01-dev</version>
+    <creationDate>2026-05-31</creationDate>
+    <infourl title='Package - MokoJoomOpenGraph'>https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/releases/tag/development</infourl>
+    <downloads>
+      <downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/releases/download/development/pkg_mokoog-01.00.01-dev.zip</downloadurl>
+    </downloads>
+    <sha256>183fde7dcc8e6c00a4cf063165556d5548f4ea5c553be7c2efa7e7e073866403</sha256>
+    <tags><tag>dev</tag></tags>
+    <changelogurl>https://git.mokoconsulting.tech/MokoConsulting/MokoJoomOpenGraph/raw/branch/main/CHANGELOG.md</changelogurl>
+    <maintainer>Moko Consulting</maintainer>
+    <maintainerurl>https://mokoconsulting.tech</maintainerurl>
+    <targetplatform name="joomla" version="(5|6)\..*" />
+  </update>
 </updates>