From f76cd94c64adbc5df3ec3aeb3475dbfb9f13a51f Mon Sep 17 00:00:00 2001
From: Jonathan Miller <jmiller-moko@noreply.git.mokoconsulting.tech>
Date: Mon, 25 May 2026 21:23:17 -0500
Subject: [PATCH] chore: update CLAUDE.md with current architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Language: HCL → PHP 8.1+
- Added directory layout table (cli/, validate/, lib/, etc.)
- Added CliFramework pattern for new tools
- Added code quality section (PHPCS, PHPStan levels)
- Added common commands (bin/moko, phpcs, phpstan)
- Added rules for new CLI tools and COMMAND_MAP registration

Closes #103

Authored-by: Moko Consulting
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 74 insertions(+), 8 deletions(-)

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