Add wfctl docs generate command for Markdown + Mermaid documentation generation

cmd/wfctl/main.go

@@ -58,6 +58,7 @@ var commands = map[string]func([]string) error{
 	"mcp":       runMCP,
 	"modernize": runModernize,
 	"infra":     runInfra,
+	"docs":      runDocs,
 }
 
 func main() {

cmd/wfctl/wfctl.yaml

@@ -55,6 +55,8 @@ workflows:
         description: "Detect and fix known YAML config anti-patterns (dry-run by default)"
       - name: infra
         description: "Manage infrastructure lifecycle (plan, apply, status, drift, destroy)"
+      - name: docs
+        description: "Generate documentation from workflow configs (generate: produce Markdown + Mermaid diagrams)"
 
 # Each command is expressed as a workflow pipeline triggered by the CLI.
 # The pipeline delegates to the registered Go implementation via step.cli_invoke,
@@ -348,3 +350,14 @@ pipelines:
         config:
           command: infra
 
+  cmd-docs:
+    trigger:
+      type: cli
+      config:
+        command: docs
+    steps:
+      - name: run
+        type: step.cli_invoke
+        config:
+          command: docs
+

docs/WFCTL.md

@@ -119,6 +119,7 @@ graph TD
 | **Validation & Inspection** | `validate`, `inspect`, `schema`, `compat check`, `template validate` |
 | **API & Contract** | `api extract`, `contract test`, `diff` |
 | **Deployment** | `deploy docker/kubernetes/helm/cloud`, `build-ui`, `generate github-actions` |
+| **Documentation** | `docs generate` |
 | **Plugin Management** | `plugin`, `registry`, `publish` |
 | **UI Generation** | `ui scaffold`, `build-ui` |
 | **Database Migrations** | `migrate status/diff/apply` |
@@ -819,6 +820,42 @@ wfctl infra destroy --auto-approve infra.yaml
 
 ---
 
+### `docs generate`
+
+Generate Markdown documentation with Mermaid diagrams from a workflow configuration file. Produces a set of `.md` files describing modules, pipelines, workflows, external plugins, and system architecture.
+
+```
+wfctl docs generate [options] <config.yaml>
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `-output` | `./docs/generated/` | Output directory for generated documentation |
+| `-plugin-dir` | _(none)_ | Directory containing external plugin manifests (`plugin.json`) |
+| `-title` | _(derived from config filename)_ | Application title used in the README |
+
+**Generated files:**
+
+| File | Description |
+|------|-------------|
+| `README.md` | Application overview with metrics, required plugins, and documentation index |
+| `modules.md` | Module inventory table, type breakdown, configuration details, and dependency graph (Mermaid) |
+| `pipelines.md` | Pipeline definitions with trigger info, step tables, workflow diagrams (Mermaid), and compensation steps |
+| `workflows.md` | HTTP routes with route diagrams (Mermaid), messaging subscriptions/producers, and state machine diagrams (Mermaid) |
+| `plugins.md` | External plugin details including version, capabilities, module/step types, and dependencies (only when `-plugin-dir` is provided) |
+| `architecture.md` | System architecture diagram with layered subgraphs and plugin architecture (Mermaid) |
+
+**Examples:**
+
+```bash
+wfctl docs generate workflow.yaml
+wfctl docs generate -output ./docs/ workflow.yaml
+wfctl docs generate -output ./docs/ -plugin-dir ./plugins/ workflow.yaml
+wfctl docs generate -output ./docs/ -title "Order Service" workflow.yaml
+```
+
+---
+
 ### `api extract`
 
 Parse a workflow config file offline and output an OpenAPI 3.0 specification of all HTTP endpoints defined in the config.

example/docs-with-plugins/README.md

@@ -0,0 +1,66 @@
+# Documentation Generation Example
+
+This example demonstrates how to use `wfctl docs generate` to produce Markdown
+documentation with Mermaid diagrams from a workflow configuration file.
+
+## Configuration
+
+The `workflow.yaml` file describes a **Secure Order Processing API** that uses:
+
+- HTTP server with routing and middleware
+- JWT authentication and authorization (via `workflow-plugin-authz`)
+- Messaging / event publishing
+- A state machine for order lifecycle management
+- Pipelines with validation, HTTP calls, and compensation steps
+- Storage (SQLite)
+- Observability (metrics, health checks)
+- Sidecars (Redis cache, Jaeger tracing)
+
+## Generating Documentation
+
+```bash
+# From this directory:
+wfctl docs generate \
+  -output ./docs/ \
+  -plugin-dir ./plugins/ \
+  workflow.yaml
+```
+
+This creates the following files in `./docs/`:
+
+| File | Description |
+|------|-------------|
+| `README.md` | Application overview with stats and index |
+| `modules.md` | Module inventory, types, and dependency graph |
+| `pipelines.md` | Pipeline definitions with workflow diagrams |
+| `workflows.md` | HTTP routes, messaging, and state machine diagrams |
+| `plugins.md` | External plugin details and capabilities |
+| `architecture.md` | System architecture diagram |
+
+## External Plugins
+
+The `plugins/` directory contains a `plugin.json` manifest for
+[GoCodeAlone/workflow-plugin-authz](https://github.com/GoCodeAlone/workflow-plugin-authz),
+which provides authorization enforcement capabilities:
+
+- **Module types:** `authz.enforcer`, `authz.policy`
+- **Step types:** `step.authz_check`, `step.authz_grant`
+- **Capabilities:** `authorization` (provider)
+
+The documentation generator reads these manifests to produce a dedicated
+plugins page describing each plugin's version, dependencies, module types,
+step types, and capabilities.
+
+## Viewing on GitHub
+
+All generated `.md` files use standard Markdown. Mermaid diagrams are embedded
+in fenced code blocks with the `mermaid` language tag:
+
+````markdown
+```mermaid
+graph LR
+    A --> B
+```
+````
+
+GitHub automatically renders these as SVG diagrams when viewed in the browser.

example/docs-with-plugins/plugins/workflow-plugin-authz/plugin.json

@@ -0,0 +1,63 @@
+{
+  "name": "workflow-plugin-authz",
+  "version": "1.2.0",
+  "author": "GoCodeAlone",
+  "description": "Authorization plugin for workflow engine providing RBAC, ABAC, and policy-based access control for HTTP endpoints and pipeline steps.",
+  "license": "MIT",
+  "repository": "https://github.com/GoCodeAlone/workflow-plugin-authz",
+  "tier": "community",
+  "tags": ["authorization", "rbac", "abac", "security", "access-control"],
+  "moduleTypes": ["authz.enforcer", "authz.policy"],
+  "stepTypes": ["step.authz_check", "step.authz_grant"],
+  "triggerTypes": [],
+  "workflowTypes": [],
+  "wiringHooks": ["authz-middleware-injection"],
+  "capabilities": [
+    {
+      "name": "authorization",
+      "role": "provider",
+      "priority": 10
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "workflow-plugin-http",
+      "constraint": ">=1.0.0"
+    }
+  ],
+  "stepSchemas": [
+    {
+      "type": "step.authz_check",
+      "description": "Check if the current request is authorized for a given permission",
+      "configFields": [
+        {
+          "key": "permission",
+          "label": "Permission",
+          "type": "string",
+          "description": "The permission string to check (e.g. 'orders:read')",
+          "required": true
+        }
+      ]
+    },
+    {
+      "type": "step.authz_grant",
+      "description": "Grant a permission to a role or user",
+      "configFields": [
+        {
+          "key": "role",
+          "label": "Role",
+          "type": "string",
+          "description": "Target role to grant permission to",
+          "required": true
+        },
+        {
+          "key": "permission",
+          "label": "Permission",
+          "type": "string",
+          "description": "Permission to grant",
+          "required": true
+        }
+      ]
+    }
+  ]
+}