Add sample external plugin collection

Author: marcofortina

README.md

@@ -496,3 +496,6 @@ python scripts/check-python39-compat.py
 
 
 Release packages can be validated with `scripts/package-release-smoke.sh --output-dir dist/package-release-smoke`.
+
+
+A sample external plugin collection is available in `examples/external-plugins/`.

docs/guides/creating-plugins.md

@@ -115,3 +115,6 @@ writes `automax-plugins.lock.json` with the installed package checksum.
 directory to `--plugin-path` loads every top-level `.py` file and verified,
 lock-matching `.zip` package it contains, so operators can keep a stable plugin
 directory instead of listing each package path on every command.
+
+
+A packaged sample collection is available in `examples/external-plugins/` and exports `company.demo.hello`.

docs/guides/sample-external-plugin.md

@@ -0,0 +1,18 @@
+<!--
+Copyright (C) 2026 Marco Fortina
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Sample external plugin collection
+
+Automax ships a small external plugin example under `examples/external-plugins/`. It validates the external plugin SDK packaging workflow without requiring a private plugin repository.
+
+```bash
+automax plugins check examples/external-plugins/company/plugins
+automax plugins package examples/external-plugins/company/plugins --output dist/company-demo-plugins.zip --force
+automax plugins verify-package dist/company-demo-plugins.zip
+automax plugins index dist/company-demo-plugins.zip --output dist/automax-plugins-index.json
+automax plugins install-package dist/company-demo-plugins.zip --dest-dir .automax/plugins --force
+```
+
+The sample plugin exports `company.demo.hello` and is intentionally deterministic so it can be used in release and packaging smoke checks.

examples/external-plugins/README.md

@@ -0,0 +1,18 @@
+<!--
+Copyright (C) 2026 Marco Fortina
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Sample external plugins
+
+This directory contains a minimal external plugin collection used to validate the package, verify, index and install workflows.
+
+```bash
+automax plugins check examples/external-plugins/company/plugins
+automax plugins package examples/external-plugins/company/plugins --output dist/company-demo-plugins.zip --force
+automax plugins verify-package dist/company-demo-plugins.zip
+automax plugins index dist/company-demo-plugins.zip --output dist/automax-plugins-index.json
+automax plugins install-package dist/company-demo-plugins.zip --dest-dir .automax/plugins --force
+```
+
+The sample plugin is `company.demo.hello`.

examples/external-plugins/company/plugins/company_demo.py

@@ -0,0 +1,51 @@
+# Copyright (C) 2026 Marco Fortina
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Sample external Automax plugin."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from automax.core.models import ExecutionContext, PluginResult
+from automax.plugins.base import BasePlugin
+
+
+class CompanyDemoHelloPlugin(BasePlugin):
+    """Return a deterministic greeting for package and install smoke tests."""
+
+    name = "company.demo.hello"
+    description = "Return a deterministic external plugin greeting."
+    category = "company"
+    required_params = ("message",)
+    optional_params = ("changed",)
+    parameter_schema = {
+        "message": {
+            "type": "string",
+            "description": "Greeting message returned by the plugin.",
+            "non_empty": True,
+        },
+        "changed": {
+            "type": "boolean",
+            "default": False,
+            "description": "Whether the plugin should report a change.",
+        },
+    }
+    examples = (
+        """- id: hello\n  use: company.demo.hello\n  with:\n    message: hello""",
+    )
+    result_fields = {
+        "message": "Rendered greeting.",
+        "changed": "Whether the plugin reported a change.",
+    }
+    supports_dry_run = True
+    supports_check_mode = True
+
+    def execute(self, params: Dict[str, object], context: ExecutionContext) -> PluginResult:
+        message = str(params["message"])
+        changed = bool(params.get("changed", False))
+        return PluginResult.success(
+            changed=changed,
+            message=message,
+            data={"message": message, "changed": changed},
+        )

mkdocs.yml

@@ -77,6 +77,7 @@ nav:
     - Package Release Smoke: guides/package-release-smoke.md
     - Example Indexes: guides/example-indexes.md
     - External Plugin Signing Policy: guides/external-plugin-signing-policy.md
+    - Sample External Plugin: guides/sample-external-plugin.md
     - Run Event Stream: guides/run-event-stream.md
     - Publishing Documentation: guides/publishing-docs.md
   - Reference:

tests/test_documentation_and_regressions.py

@@ -2097,6 +2097,23 @@ def test_runtime_evidence_suite_is_documented_and_optional():
     assert "set AUTOMAX_SSH_HOST and AUTOMAX_SSH_USER" in result.stderr
 
 
+def test_sample_external_plugin_collection_is_documented():
+    docs = "\n".join(
+        path.read_text(encoding="utf-8")
+        for path in [
+            Path("README.md"),
+            Path("examples/external-plugins/README.md"),
+            Path("docs/guides/sample-external-plugin.md"),
+            Path("docs/guides/creating-plugins.md"),
+            Path("mkdocs.yml"),
+        ]
+    )
+
+    assert "company.demo.hello" in docs
+    assert "examples/external-plugins" in docs
+    assert "Sample External Plugin: guides/sample-external-plugin.md" in docs
+
+
 def test_external_plugin_signing_policy_is_documented_and_release_wired(tmp_path: Path):
     script = Path("scripts/check-plugin-index-policy.sh").read_text(encoding="utf-8")
     release = Path("scripts/release-check.sh").read_text(encoding="utf-8")

tests/test_engine.py

@@ -2083,6 +2083,29 @@ def test_plugins_init_check_package_external_sdk(tmp_path: Path):
     assert validate.exit_code == 0, validate.output
 
 
+def test_sample_external_plugin_collection_can_be_packaged_and_indexed(tmp_path: Path):
+    from automax.plugins.sdk import (
+        build_plugin_package_index,
+        package_external_plugin_path,
+        verify_external_plugin_package,
+    )
+
+    package = tmp_path / "company-demo-plugins.zip"
+
+    package_external_plugin_path(
+        "examples/external-plugins/company/plugins",
+        str(package),
+        force=True,
+    )
+    verified = verify_external_plugin_package(str(package))
+    indexed = build_plugin_package_index([str(package)])
+
+    assert verified["ok"] is True
+    assert verified["plugins"] == ["company.demo.hello"]
+    assert indexed["ok"] is True
+    assert indexed["plugin_count"] == 1
+
+
 def test_plugins_index_writes_verified_package_repository_index(tmp_path: Path):
     plugin_dir = tmp_path / "plugins"
     package_path = tmp_path / "packages" / "demo-plugin.zip"