Plugin authoring guide exists

Without a plugin authoring guide, a developer who wants to extend the system must reverse-engineer existing plugins and read the host's internal source code. This creates a barrier that collapses the potential plugin ecosystem to however many developers are willing to invest that archaeology time — typically zero third-party developers. ISO 25010 maintainability.analysability scores fall when the system cannot be understood without execution; an authoring guide is the primary mechanism for making the plugin API understandable before writing code.

Create a docs/plugins.md or docs/plugin-authoring-guide.md that covers the complete authoring workflow from manifest creation through testing. Include a working code example for each major step.

# Creating a Plugin

## 1. Create the manifest
Create a `plugin.json` file with `name`, `version`, and `engines.host-api`.

## 2. Implement the plugin
Export a class implementing the `Plugin` interface from `'host/plugin-api'`.

## 3. Register hooks
In your `activate()` method, call `context.hooks.on('before:request', handler)`.

## 4. Test your plugin
Use `createTestHost()` from `'host/testing'` to run your plugin in isolation.

## 5. Distribute
Publish to npm with the `my-app-plugin` keyword.

• ID: plugin-extension-architecture.discovery-docs.authoring-guide

• Severity: high

• What to look for: Check for documentation that explains how to create a plugin from scratch. This is different from API reference — it's a narrative guide that walks a developer through the process. Look for:

  1. A dedicated "Creating a Plugin" or "Plugin Authoring Guide" page in docs
  2. A "Plugins" section in the README with authoring instructions
  3. A CONTRIBUTING.md that covers plugin development
  4. Step-by-step instructions: (a) create manifest, (b) implement plugin interface, (c) register hooks, (d) test, (e) distribute The guide must cover: what the plugin interface looks like, what lifecycle methods to implement, how to register hook handlers, and how to test the plugin. If the guide just says "implement the Plugin interface" with no details, it fails.

• Pass criteria: Count all documentation pages or sections for plugin authors. A guide exists that explains the complete plugin authoring workflow: creating the manifest/metadata, implementing the plugin interface, registering hooks, accessing the plugin API, and testing. The guide includes code examples for each step. At least 1 authoring guide must exist with setup instructions and API reference.

• Fail criteria: No authoring guide. Plugin authors must reverse-engineer existing plugins or read host source code to understand how to build a plugin. OR a guide exists but only covers installation/usage of existing plugins, not creation of new ones.

• Skip (N/A) when: The plugin system is internal-only with no third-party developers, AND all plugin authors have direct access to the host source code and team knowledge. Even then, consider this a fail — internal developers also benefit from authoring guides.

• Detail on fail: "No plugin authoring documentation exists. The README mentions 'extensible via plugins' but doesn't explain how to create one. A developer looking to build a plugin would need to study existing plugins' source code and the PluginManager implementation to understand the expected interface, lifecycle, and registration process."

• Remediation: An authoring guide is the single highest-leverage documentation for a plugin system. Without it, your potential plugin ecosystem stalls.

  # Creating a Plugin
  
  ## 1. Create the manifest
  Create a `plugin.json` file: ...
  
  ## 2. Implement the plugin
  Your plugin must export a class implementing `Plugin`: ...
  
  ## 3. Register hooks
  In your `activate()` method, register handlers: ...
  
  ## 4. Test your plugin
  Use `createTestHost()` to run your plugin in isolation: ...
  
  ## 5. Distribute
  Publish to npm with the `my-app-plugin` keyword: ...