.mokogitea/workflows/issue-branch.yml

@@ -5,7 +5,7 @@
 # FILE INFORMATION
 # DEFGROUP: Gitea.Workflow
 # INGROUP: mokocli.Automation
-# VERSION: 01.00.00
+# VERSION: 09.34.01
 # BRIEF: Auto-create feature branch when an issue is opened
 
 name: "Universal: Issue Branch"

README.md

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

automation/update_dependencies.php

@@ -13,7 +13,7 @@
  * INGROUP: MokoPlatform.Scripts
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
  * PATH: /automation/update_dependencies.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Cross-repo dependency update automation — scan, update, PR, auto-merge
  */
 

cli/branch_rename.php

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

cli/bulk_workflow_push.php

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

cli/bulk_workflow_trigger.php

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

cli/client_dashboard.php

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

cli/client_inventory.php

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

cli/client_provision.php

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

cli/grafana_dashboard.php

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

cli/joomla_build.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/joomla_build.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Build a Joomla extension ZIP from manifest — all types supported
  * NOTE: Called by pre-release and auto-release workflows.
  */

cli/joomla_metadata_validate.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/joomla_metadata_validate.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Validate MokoGitea repo metadata against Joomla extension manifest XML
  */
 

cli/manifest_detect.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/manifest_detect.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Auto-detect manifest fields from source files and optionally push to API
  */
 

cli/manifest_integrity.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/manifest_integrity.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Cross-check manifest API fields against repo contents across the org
  */
 

cli/manifest_licensing.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/manifest_licensing.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Ensure licensing tags (updateservers, dlid) in Joomla extension manifests
  */
 

cli/manifest_read.php

@@ -10,7 +10,7 @@
  * INGROUP: mokocli
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
  * PATH: /cli/manifest_read.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Read repo metadata from Gitea manifest API, auto-detect the rest
  */
 

cli/platform_detect.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/platform_detect.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Auto-detect repository platform type and optionally update manifest
  */
 

cli/release_cascade.php

@@ -10,7 +10,7 @@
  * INGROUP: mokocli
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
  * PATH: /cli/release_cascade.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Cascade release zip to all lower stability channels
  */
 

cli/release_publish.php

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

cli/scaffold_client.php

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

cli/updates_xml_sync.php

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

cli/version_auto_bump.php

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

cli/version_bump.php

@@ -370,7 +370,7 @@ class VersionBumpCli extends CliFramework
     /**
      * Scan git release tags for the highest version across all channels.
      *
-     * Checks release names like "MokoSuiteClient (VERSION: 02.45.00)" in
+     * Checks release names like "MokoSuiteClient (VERSION: 09.34.01)" in
      * git tags (stable, release-candidate, development, etc.) to find the
      * highest version that has been released on any channel.
      */

cli/version_check.php

@@ -10,7 +10,7 @@
  * INGROUP: mokoplatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /cli/version_check.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Validate version consistency across README, manifests, and sub-packages
  */
 

cli/wiki_sync.php

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

cli/workflow_sync.php

@@ -10,7 +10,7 @@
  * INGROUP: moko-platform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
  * PATH: /cli/workflow_sync.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Sync workflows from Generic → platform templates → live repos based on manifest.platform
  */
 

deploy/backup-before-deploy.php

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

deploy/deploy-dolibarr.php

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

deploy/health-check.php

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

deploy/rollback-joomla.php

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

deploy/sync-joomla.php

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

lib/Enterprise/CliFramework.php

@@ -590,6 +590,25 @@ abstract class CliFramework
         $this->display('  ' . $this->c($color . self::C_BOLD, $icon) . '  ' . $label . $suffix . "\n");
     }
 
+    /**
+     * Display a recovery suggestion with a lightbulb prefix.
+     *
+     * @param string $suggestion Fix suggestion text (from RecoverySuggestion)
+     */
+    protected function suggest(string $suggestion): void
+    {
+        if ($this->quiet) {
+            return;
+        }
+        $this->clearProgress();
+        $lines = explode("\n", $suggestion);
+        $first = array_shift($lines);
+        $this->display('  ' . $this->c(self::C_YELLOW, '💡 ' . $first) . "\n");
+        foreach ($lines as $line) {
+            $this->display('  ' . $this->c(self::C_YELLOW, '   ' . $line) . "\n");
+        }
+    }
+
     // =========================================================================
     // Console graphics — progress bar
     // =========================================================================

lib/Enterprise/RecoverySuggestion.php

@@ -0,0 +1,93 @@
+#!/usr/bin/env php
+<?php
+
+/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ * FILE INFORMATION
+ * DEFGROUP: MokoPlatform.Enterprise
+ * INGROUP: MokoPlatform.Lib
+ * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokocli
+ * PATH: /lib/Enterprise/RecoverySuggestion.php
+ * BRIEF: Smart error recovery suggestions for validators
+ */
+
+declare(strict_types=1);
+
+namespace MokoCli;
+
+/**
+ * Generates actionable fix suggestions when validators detect problems.
+ *
+ * Each method returns a human-readable suggestion string that tells the
+ * developer exactly what to do to fix the issue.
+ */
+class RecoverySuggestion
+{
+    /**
+     * Suggest creating a missing required file.
+     */
+    public static function forMissingFile(string $file, string $template = ''): string
+    {
+        $suggestion = "Create the missing file: {$file}";
+        if ($template !== '') {
+            $suggestion .= "\n    Copy from template: {$template}";
+        }
+        return $suggestion;
+    }
+
+    /**
+     * Suggest adding a missing XML element.
+     */
+    public static function forMissingXmlElement(string $element, string $value, string $file, int $afterLine = 0): string
+    {
+        $snippet = "<{$element}>{$value}</{$element}>";
+        if ($afterLine > 0) {
+            return "Add {$snippet} after line {$afterLine} in {$file}";
+        }
+        return "Add {$snippet} to {$file}";
+    }
+
+    /**
+     * Suggest fixing a version mismatch.
+     */
+    public static function forVersionMismatch(string $file, string $found, string $expected): string
+    {
+        return "Update version in {$file}: change \"{$found}\" to \"{$expected}\"";
+    }
+
+    /**
+     * Suggest creating a missing directory.
+     */
+    public static function forMissingDirectory(string $dir): string
+    {
+        return "Create the missing directory:\n    mkdir -p {$dir}";
+    }
+
+    /**
+     * Suggest fixing a syntax error.
+     */
+    public static function forSyntaxError(string $file, int $line, string $error): string
+    {
+        return "Fix syntax error at {$file}:{$line}\n    {$error}";
+    }
+
+    /**
+     * Suggest fixing a missing license header.
+     */
+    public static function forMissingHeader(string $file): string
+    {
+        return "Add SPDX license header to {$file}:\n    /* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>\n     * SPDX-License-Identifier: GPL-3.0-or-later */";
+    }
+
+    /**
+     * Suggest running a command to fix an issue.
+     */
+    public static function forCommand(string $command, string $context = ''): string
+    {
+        $suggestion = "Run: {$command}";
+        if ($context !== '') {
+            $suggestion = "{$context}\n    {$suggestion}";
+        }
+        return $suggestion;
+    }
+}

mcp/servers/mokocrm_api/CONTRIBUTING.md

@@ -14,7 +14,7 @@
 	DEFGROUP: dolibarr-api-mcp.Documentation
 	INGROUP: dolibarr-api-mcp
 	REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
-	VERSION: 09.34.00
+	VERSION: 09.34.01
 	PATH: ./CONTRIBUTING.md
 	BRIEF: Contribution guidelines for the project
 -->

mcp/servers/mokocrm_api/SECURITY.md

@@ -10,7 +10,7 @@ DEFGROUP: dolibarr-api-mcp.Documentation
 INGROUP: dolibarr-api-mcp
 REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
 PATH: /SECURITY.md
-VERSION: 09.34.00
+VERSION: 09.34.01
 BRIEF: Security vulnerability reporting and handling policy
 -->
 

mcp/servers/mokosuite_api/CONTRIBUTING.md

@@ -14,7 +14,7 @@
 	DEFGROUP: 
 	INGROUP: Project.Documentation
 	REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoCli-Template-Generic
-	VERSION: 09.34.00
+	VERSION: 09.34.01
 	PATH: ./CONTRIBUTING.md
 	BRIEF: Contribution guidelines for the project
 -->

mcp/servers/mokosuite_api/SECURITY.md

@@ -23,7 +23,7 @@ DEFGROUP: [PROJECT_NAME]
 INGROUP: [PROJECT_NAME].Documentation
 REPO: [REPOSITORY_URL]
 PATH: /SECURITY.md
-VERSION: 09.34.00
+VERSION: 09.34.01
 BRIEF: Security vulnerability reporting and handling policy
 -->
 

tests/Unit/VersionBumpTest.php

@@ -63,7 +63,7 @@ class VersionBumpTest extends TestCase
     {
         file_put_contents(
             "{$this->tmpDir}/README.md",
-            "<!-- VERSION: 09.34.00 -->\nSome content\n"
+            "<!-- VERSION: 09.34.01 -->\nSome content\n"
         );
 
         $this->execute();

tests/Unit/VersionReadTest.php

@@ -34,7 +34,7 @@ class VersionReadTest extends TestCase
     {
         file_put_contents(
             "{$this->tmpDir}/README.md",
-            "# Test\n<!-- VERSION: 09.34.00 -->\n"
+            "# Test\n<!-- VERSION: 09.34.01 -->\n"
         );
 
         $this->assertSame('02.03.04', trim($this->runScript()));
@@ -68,7 +68,7 @@ class VersionReadTest extends TestCase
     {
         file_put_contents(
             "{$this->tmpDir}/README.md",
-            "<!-- VERSION: 09.34.00 -->\n"
+            "<!-- VERSION: 09.34.01 -->\n"
         );
         mkdir("{$this->tmpDir}/src", 0755, true);
         file_put_contents(

validate/check_file_integrity.php

@@ -12,7 +12,7 @@
  * INGROUP: MokoPlatform
  * REPO: https://git.mokoconsulting.tech/MokoConsulting/mokoplatform
  * PATH: /validate/check_file_integrity.php
- * VERSION: 09.34.00
+ * VERSION: 09.34.01
  * BRIEF: Compare deployed files on a remote server against the local repository to detect drift
  */
 

validate/check_structure.php

@@ -20,6 +20,7 @@ declare(strict_types=1);
 require_once __DIR__ . '/../vendor/autoload.php';
 
 use MokoCli\CliFramework;
+use MokoCli\RecoverySuggestion;
 
 /**
  * Validates that the required directories and files exist in the repository root.
@@ -67,6 +68,7 @@ class CheckStructure extends CliFramework
             if (!is_dir($path . '/' . $dir)) {
                 $missingDirs[] = $dir;
                 $this->status(false, "Directory: {$dir}");
+                $this->suggest(RecoverySuggestion::forMissingDirectory($dir));
                 $failed++;
             } else {
                 $this->status(true, "Directory: {$dir}");
@@ -96,6 +98,7 @@ class CheckStructure extends CliFramework
             if (!is_file($path . '/' . $file)) {
                 $missingFiles[] = $file;
                 $this->status(false, "File: {$file}");
+                $this->suggest(RecoverySuggestion::forMissingFile($file));
                 $failed++;
             } else {
                 $this->status(true, "File: {$file}");

validate/check_version_consistency.php

@@ -21,6 +21,7 @@ declare(strict_types=1);
 require_once __DIR__ . '/../vendor/autoload.php';
 
 use MokoCli\CliFramework;
+use MokoCli\RecoverySuggestion;
 
 /**
  * Checks that the version recorded in composer.json matches VERSION headers
@@ -101,6 +102,7 @@ class CheckVersionConsistency extends CliFramework
                     if ($match[0] !== $expected) {
                         $line = substr_count(substr($content, 0, (int) $match[1]), "\n") + 1;
                         $this->status(false, $filename, "line {$line}: found {$match[0]}, expected {$expected}");
+                        $this->suggest(RecoverySuggestion::forVersionMismatch($filename, $match[0], $expected));
                         $issues[] = $filename;
                         $filePassed = false;
                     }