docs: add plugin development guide

docs/guide/plugin-development.md

@@ -0,0 +1,77 @@
+# Plugin Development Guide
+
+Mivo supports a modular plugin system that allows developers to extend functionality, add themes, or integrate third-party services. This guide details the rules and structure required for your plugin to work with Mivo and appear in the Registry.
+
+## Directory Structure
+
+A valid Mivo plugin must have a flat structure with a `plugin.php` file in the root.
+
+```text
+plugin-name/
+├── plugin.php          # (Required) Entry point & Metadata
+├── composer.json       # (Optional) Dependencies
+├── README.md           # (Required) Documentation for Registry
+├── theme/              # (Optional) Captive Portal theme files
+│   └── styles.css
+└── src/                # (Optional) PHP Classes
+```
+
+## Metadata Header
+
+Your `plugin.php` **must** start with a specific comment block. The Registry crawler uses this to categorize and display your plugin.
+
+```php
+<?php
+/**
+ * Plugin Name: My Awesome Plugin
+ * Description: Adds a dark mode toggle to the hotspot login page.
+ * Version: 1.0.0
+ * Author: YourName
+ * Category: Hotspot Tools
+ * Tags: theme, dark-mode, ui
+ * Core Version: >=1.2.0
+ */
+
+use App\Services\Hook;
+
+// Plugin logic starts here...
+```
+
+### Required Fields
+- **Plugin Name**: Displayed title.
+- **Description**: Short summary (max 160 chars).
+- **Version**: SemVer format (e.g., `1.0.0`).
+- **Category**: One of: `Hotspot Tools`, `System Tools`, `Payment Gateway`, `Reports`.
+- **Tags**: Comma-separated search keywords.
+
+## Release & Registry Rules
+
+To get your plugin listed in the [Official Registry](/plugins/):
+
+1.  **Public Repository**: Host your code on GitHub.
+2.  **Naming**: Repository name should start with `plugin-` (e.g., `plugin-advanced-login`).
+3.  **Versioning**: Use **Git Tags** for releases. The Registry strictly prefers tagged releases over the main branch.
+    -   Tag format: `v1.0.0`.
+    -   You can use GitHub Actions to auto-generate ZIPs.
+4.  **Documentation**: A comprehensive `README.md` is mandatory. It will be mirrored to the Mivo website.
+
+## Sample GitHub Workflow
+
+Create `.github/workflows/release.yml` to automatically package your plugin:
+
+```yaml
+name: Release Plugin
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: zip -r plugin.zip . -x "*.git*"
+      - uses: softprops/action-gh-release@v1
+        with:
+          files: plugin.zip
+```