docs: working methodology and CLI patterns

docs/03-WORKING-METHODOLOGY.md

@@ -0,0 +1,144 @@
+# Working Methodology
+
+## VPS Access Pattern
+
+All work goes through the `asktam-mcp` connector tools. The container is `mainwp`.
+
+```
+vps_write_file  → /tmp/script.php
+vps_run_command → docker cp /tmp/script.php mainwp:/tmp/script.php
+vps_run_command → docker exec mainwp php -l /tmp/script.php   (syntax check first)
+vps_run_command → docker exec mainwp php /tmp/script.php      (execute)
+```
+
+For plugin file deployment:
+```
+docker cp /tmp/MyFile.php mainwp:/var/www/html/wp-content/plugins/advanced-mcp-plugin/includes/Tools/MyFile.php
+```
+
+## PHP CLI Script Header — Always Required
+
+Every PHP script that boots WordPress must start with exactly this:
+
+```php
+<?php
+$_SERVER['HTTP_HOST'] = 'mainwp.asktam.net';
+$_SERVER['REQUEST_URI'] = '/';
+define('WP_ADMIN', true);
+define('DOING_CRON', true);   // ← required for ElementorData CLI fix
+require '/var/www/html/wp-load.php';
+```
+
+## Calling MCP Tools Directly in Scripts
+
+```php
+$reg = new \AskTamMCP\MCP\Registry();
+$result = call_user_func($reg->getHandler('tool_name'), [
+    'arg1' => 'value1',
+    'arg2' => 'value2',
+]);
+```
+
+## Building Elementor Pages — Full Pattern
+
+```php
+define('WP_ADMIN', true);
+define('DOING_CRON', true);          // ← mandatory
+require '/var/www/html/wp-load.php';
+
+$reg = new \AskTamMCP\MCP\Registry();
+
+// 1. Create page as draft — no template yet
+$pid = wp_insert_post([
+    'post_title'  => 'My Page',
+    'post_status' => 'draft',
+    'post_type'   => 'page',
+    'meta_input'  => ['_elementor_edit_mode' => 'builder'],
+]);
+
+// 2. Add sections via Elementor tools
+$hero = call_user_func($reg->getHandler('elementor_add_container'), [
+    'post_id'  => $pid,
+    'settings' => ['background_color' => '#1e293b', 'min_height' => ['size'=>100,'unit'=>'vh']],
+]);
+$hid = $hero['element_id'];
+
+call_user_func($reg->getHandler('elementor_add_heading'), [
+    'post_id'      => $pid,
+    'container_id' => $hid,
+    'title'        => 'Your Headline',
+    'tag'          => 'h1',
+    'settings'     => ['title_color' => '#ffffff'],
+]);
+
+// 3. Publish — NO page_template in wp_update_post
+wp_update_post(['ID' => $pid, 'post_status' => 'publish']);
+
+// 4. Set template via meta AFTER publish
+update_post_meta($pid, '_wp_page_template', 'elementor-full-width');
+
+// 5. Regenerate Elementor CSS
+if (class_exists('\Elementor\Core\Files\CSS\Post')) {
+    (new \Elementor\Core\Files\CSS\Post($pid))->update();
+}
+```
+
+## Gitea Commits
+
+Use `gitea_create_or_update_file` MCP tool. The `content` parameter is the new file content written directly — not a path, not a file read. Write the content inline.
+
+```
+gitea_create_or_update_file:
+  repo_name: advanced-mcp-plugin
+  file_path: includes/Tools/MyTools.php
+  content: "<?php\n..."
+  message: "feat: add my new tool"
+  branch: main
+```
+
+## Syntax Check Before Deploy
+
+Always check before copying a PHP file into the plugin:
+
+```bash
+docker exec mainwp php -l /tmp/MyFile.php
+```
+
+Expected output: `No syntax errors detected in /tmp/MyFile.php`
+
+## wp_mail in CLI Context
+
+The mainwp container has no sendmail binary. The PHP ini override at `/usr/local/etc/php/conf.d/mcp-mail.ini` routes all mail to `/bin/true` (no-op) in CLI context. This is intentional — do not remove it.
+
+## Test Suite
+
+Two test scripts exist at `/tmp/` on the VPS:
+
+```bash
+docker exec mainwp php /tmp/test_93.php        # original 93 tools
+docker exec mainwp php /tmp/test_new_tools.php # 30 new tools
+```
+
+Expected results:
+- `test_93.php`: 74 OK / 2 test-data errors / 16 safe skips / 0 missing
+- `test_new_tools.php`: 24 OK / 3 test-data errors / 2 safe skips
+
+After any plugin change run both to verify nothing regressed.
+
+## Security Audit
+
+```bash
+docker cp /tmp/security_audit_v2.php mainwp:/tmp/security_audit_v2.php
+docker exec mainwp php /tmp/security_audit_v2.php
+```
+
+Expected: `SCORE: 30/30 — Grade: A+`
+
+## Admin Panel Location
+
+WP Admin → **AskTam MCP** (top-level menu)
+
+Tabs:
+- **API Keys** — generate, revoke, set scopes
+- **Settings** — HTTPS, rate limit, request logging, raw SQL toggle
+- **Audit Log** — last 1000 calls with key_id, tool, IP, timestamp