{
  "id": "org.machanism.machai:gw-maven-plugin:1.2.0",
  "name": "org.machanism.machai:gw-maven-plugin",
  "version": "1.2.0",
  "location": {
    "repositoryType": "Maven",
    "repositoryUrl": "https://repo1.maven.org/maven2",
    "coordinates": {
      "group": "org.machanism.machai",
      "artifactId": "gw-maven-plugin",
      "version": "1.2.0",
      "extension": "jar"
    }
  },
  "description": "GW Maven Plugin is a Java Maven plugin that integrates Machai Ghostwriter into Maven builds to automate guided documentation and file processing workflows. The plugin scans project content for embedded @guidance blocks, gathers contextual instructions, resolves Maven project and reactor metadata, and delegates AI-assisted processing to the Ghostwriter engine. It supports both aggregator-style and per-module execution models, making it suitable for single-module projects, multi-module Maven reactors, repository-wide documentation maintenance, and build-integrated content generation workflows. The primary goals are gw:gw for guided file processing in reverse module order similar to the Ghostwriter CLI, gw:gw-per-module for standard reactor-ordered guided processing, gw:act for interactive or predefined action-prompt execution over scanned files, gw:act-per-module for reactor-context action execution, and gw:clean for deleting temporary workflow artifacts. Shared configuration supports provider and model selection with gw.model, optional scan-root selection with gw.path, additional instructions with gw.instructions, path filtering with gw.excludes, optional input logging with logInputs, and secure GenAI credential resolution from Maven settings.xml through genai.serverId. The plugin also exposes class-discovery and reflective inspection helper tools through org.machanism.machai.gw.maven.tools so Ghostwriter workflows can inspect project and dependency classes during processing. This artifact is best classified as a Maven build plugin for AI-assisted documentation automation, guided file processing, developer productivity, and Java project content maintenance.",
  "authors": [
    {
      "name": "Machanism.org",
      "website": "https://machai.machanism.org/gw-maven-plugin"
    }
  ],
  "license": "Apache-2.0",
  "classification": {
    "type": "plugin",
    "domains": [
      "Build Automation",
      "Documentation Automation",
      "AI-Assisted File Processing",
      "Maven Tooling",
      "Developer Productivity",
      "Guided Content Maintenance",
      "Java Project Automation"
    ],
    "languages": [
      {
        "name": "Java",
        "version": "8"
      },
      {
        "name": "XML",
        "version": "1.0"
      }
    ],
    "layers": [
      "Adapters",
      "Infrastructure"
    ],
    "usageContext": [
      "Running AI-assisted guided file processing directly from Maven goals",
      "Maintaining documentation trees that contain embedded @guidance instructions",
      "Processing repository content in single-module and multi-module Maven builds",
      "Applying predefined or interactive action prompts to documentation files",
      "Resolving GenAI provider credentials through Maven settings.xml",
      "Registering reflective class-inspection tools for Ghostwriter workflows"
    ],
    "targetEnvironment": [
      "Java",
      "Maven"
    ],
    "integrations": [
      "Machai Ghostwriter"
    ]
  },
  "constructors": [
    {
      "package": "org.machanism.machai.gw.maven",
      "signature": "public org.machanism.machai.gw.maven.GWMojo()",
      "description": "Creates the Maven mojo for the gw:gw goal. In practice, Maven instantiates this class when the plugin goal is invoked. The goal runs guided Ghostwriter file processing as an aggregator, can execute without a local pom.xml, and processes sub-modules before parent modules.",
      "examples": [
        {
          "snippet": "<plugin>\n  <groupId>org.machanism.machai</groupId>\n  <artifactId>gw-maven-plugin</artifactId>\n  <version>1.2.0</version>\n</plugin>",
          "description": "How to use it: Step 1, install the ready-to-use Maven plugin by adding it to the build/plugins section of pom.xml. Step 2, Maven will construct org.machanism.machai.gw.maven.GWMojo when the gw:gw goal is invoked."
        },
        {
          "snippet": "mvn org.machanism.machai:gw-maven-plugin:1.2.0:gw -Dgw.model=openai:gpt-4o-mini -Dgw.path=src/site",
          "description": "How to use it: Step 3, run the plugin goal from the project root. Maven creates org.machanism.machai.gw.maven.GWMojo, applies the supplied configuration, scans the selected content tree, and starts guided processing."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "signature": "public org.machanism.machai.gw.maven.GWPerModuleMojo()",
      "description": "Creates the Maven mojo for the gw:gw-per-module goal. Maven instantiates this class once per module in the active reactor build so guided processing follows standard Maven reactor ordering instead of aggregator-style traversal.",
      "examples": [
        {
          "snippet": "mvn org.machanism.machai:gw-maven-plugin:1.2.0:gw-per-module -Dgw.path=src/site",
          "description": "How to use it: Run the per-module goal in a multi-module build when each module should be processed in Maven reactor order. Maven creates org.machanism.machai.gw.maven.GWPerModuleMojo for each participating module."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "signature": "public org.machanism.machai.gw.maven.ActMojo()",
      "description": "Creates the Maven mojo for the gw:act goal. This goal applies a predefined or interactive action prompt to scanned files. If the action text is not supplied through configuration, the plugin can prompt the user interactively.",
      "examples": [
        {
          "snippet": "mvn org.machanism.machai:gw-maven-plugin:1.2.0:act -Dgw.act=\"Rewrite headings for clarity\" -Dgw.path=src/site",
          "description": "How to use it: Step 1, invoke the action goal with a concrete prompt and a scan directory. Step 2, Maven instantiates org.machanism.machai.gw.maven.ActMojo and applies the prompt to the selected files."
        },
        {
          "snippet": "mvn org.machanism.machai:gw-maven-plugin:1.2.0:act",
          "description": "How to use it: If you do not provide -Dgw.act, Maven still creates org.machanism.machai.gw.maven.ActMojo and the plugin can ask for the action text interactively through the configured prompter."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "signature": "public org.machanism.machai.gw.maven.ActPerModuleMojo()",
      "description": "Creates the Maven mojo for the gw:act-per-module goal. This variant executes action-based processing in a standard reactor build context and is intended for execution-root oriented processing in multi-module projects.",
      "examples": [
        {
          "snippet": "mvn org.machanism.machai:gw-maven-plugin:1.2.0:act-per-module -Dgw.act=\"Normalize section titles\" -Dgw.path=src/site",
          "description": "How to use it: Run the reactor-aware action goal when you want prompt-driven processing with normal Maven per-module execution semantics."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "signature": "public org.machanism.machai.gw.maven.CleanMojo()",
      "description": "Creates the Maven mojo for the gw:clean goal. Maven uses this class to delete temporary files created by Ghostwriter processing, typically during the clean phase.",
      "examples": [
        {
          "snippet": "mvn org.machanism.machai:gw-maven-plugin:1.2.0:clean",
          "description": "How to use it: Execute the cleanup goal after guided or action-based processing to remove temporary workflow artifacts from the current module base directory."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "signature": "public org.machanism.machai.gw.maven.tools.ClassFunctionalTools()",
      "description": "Creates an empty helper instance for class-discovery and reflection tool registration. Projects must be registered before the helper can resolve class information.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.maven.tools.ClassFunctionalTools tools = new org.machanism.machai.gw.maven.tools.ClassFunctionalTools();",
          "description": "How to use it: This constructor is useful when the plugin runtime wants to create the helper first and register project classes later before exposing the tools to a Ghostwriter workflow."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "signature": "public org.machanism.machai.gw.maven.tools.ClassFunctionalTools(org.apache.maven.project.MavenProject project)",
      "description": "Creates a class-discovery helper backed by a specific Maven project's classpath so reflective tool operations can resolve project and dependency classes immediately.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.maven.tools.ClassFunctionalTools tools = new org.machanism.machai.gw.maven.tools.ClassFunctionalTools(project);",
          "description": "How to use it: In plugin internals, construct the helper with the current Maven project to immediately enable project-aware class lookup and reflective inspection functions."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "signature": "public org.machanism.machai.gw.maven.tools.ClassInfoHolder(org.apache.maven.project.MavenProject project)",
      "description": "Creates a class metadata holder for a Maven project and eagerly initializes discovery data from the project's classpath, output directories, and dependency artifacts.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.maven.tools.ClassInfoHolder holder = new org.machanism.machai.gw.maven.tools.ClassInfoHolder(project);",
          "description": "How to use it: The plugin uses this constructor internally when it needs a project-scoped cache of loadable classes, origin paths, source files, and dependency coordinates."
        }
      ]
    }
  ],
  "features": [
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "execute",
      "signature": "public void execute() throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Primary feature of org.machanism.machai.gw.maven.GWMojo that runs the gw:gw goal. It executes guided file processing for a project, supports execution without a local pom.xml, and traverses modules in reverse order so child modules are handled before parents.",
      "examples": [
        {
          "snippet": "mvn gw:gw",
          "description": "How to use it: Step 1, add @guidance blocks to the files you want Ghostwriter to process. Step 2, run mvn gw:gw from the repository or project root. Step 3, review the generated or modified content."
        },
        {
          "snippet": "mvn gw:gw -Dgw.threads=true -Dgw.path=src/site -DlogInputs=true",
          "description": "How to use it: Enable parallelized processing where supported, limit the scan to documentation content, and log the resolved inputs for debugging or auditing."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "execute",
      "signature": "public void execute() throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Primary feature of org.machanism.machai.gw.maven.GWPerModuleMojo that runs guided processing once per module in the active Maven reactor. Maven controls module order using its standard dependency graph.",
      "examples": [
        {
          "snippet": "mvn gw:gw-per-module -Dgw.path=src/site",
          "description": "How to use it: Step 1, run the goal from the execution root of a multi-module build. Step 2, Maven invokes the plugin for each module in reactor order. Step 3, inspect module-level output after processing completes."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "execute",
      "signature": "public void execute() throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Primary feature of org.machanism.machai.gw.maven.ActMojo that runs the gw:act goal. It applies a configured or interactive action prompt to scanned files, enabling one-off documentation rewrites or other prompt-driven maintenance tasks.",
      "examples": [
        {
          "snippet": "mvn gw:act -Dgw.act=\"Rewrite headings for clarity\" -Dgw.path=src/site",
          "description": "How to use it: Step 1, supply a practical action prompt. Step 2, point the plugin at the documentation directory. Step 3, run the goal and inspect the transformed files."
        },
        {
          "snippet": "mvn gw:act -Dgw.acts=src/site/acts -DlogInputs=true",
          "description": "How to use it: Keep reusable act definitions in a directory, invoke the action goal, and optionally let the plugin collect the final prompt interactively while logging the scanned inputs."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "execute",
      "signature": "public void execute() throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Primary feature of org.machanism.machai.gw.maven.ActPerModuleMojo that runs action-based processing in a standard reactor context, typically focused on the execution-root project within a multi-module build.",
      "examples": [
        {
          "snippet": "mvn gw:act-per-module -Dgw.act=\"Normalize section titles\" -Dgw.path=src/site",
          "description": "How to use it: Use the per-module action variant when you want reactor-aware prompt execution instead of the aggregator behavior of gw:act."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "execute",
      "signature": "public void execute() throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Primary feature of org.machanism.machai.gw.maven.CleanMojo that deletes temporary workflow files created during Ghostwriter processing from the current module base directory.",
      "examples": [
        {
          "snippet": "mvn gw:clean",
          "description": "How to use it: Run the cleanup goal after using guided or action-based processing so temporary workflow artifacts do not remain in the working tree."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "getConfiguration",
      "signature": "protected org.machanism.macha.core.commons.configurator.PropertiesConfigurator getConfiguration() throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Shared configuration feature of org.machanism.machai.gw.maven.AbstractGWMojo that builds the processor configuration and, when a Maven server id is configured, reads the matching settings.xml server entry to copy username, password, and custom XML configuration into the runtime configurator.",
      "examples": [
        {
          "snippet": "<settings>\n  <servers>\n    <server>\n      <id>my-model-server</id>\n      <username>your-username</username>\n      <password>your-password</password>\n      <configuration>\n        <AUTH_URL>https://example.invalid/auth</AUTH_URL>\n      </configuration>\n    </server>\n  </servers>\n</settings>",
          "description": "How to use it: Step 1, define a server entry in ~/.m2/settings.xml. Step 2, invoke the plugin with -Dgenai.serverId=my-model-server. Step 3, the plugin loads those secure settings into the runtime configuration before Ghostwriter starts."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "scanDocuments",
      "signature": "protected void scanDocuments(org.machanism.machai.gw.processor.GuidanceProcessor processor) throws org.apache.maven.plugin.MojoExecutionException",
      "description": "Shared scanning feature of org.machanism.machai.gw.maven.AbstractGWMojo that applies excludes, instructions, input logging, scan root selection, and optional class helper tool registration before invoking the document processing pipeline.",
      "examples": [
        {
          "snippet": "mvn gw:gw -Dgw.instructions=src/site/guidance.md -Dgw.excludes=target,node_modules -DlogInputs=true",
          "description": "How to use it: Provide additional instructions, exclude unwanted folders, and enable input logging to refine how the shared scanning workflow selects and processes files."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven",
      "name": "readText",
      "signature": "public java.lang.String readText(java.lang.String prompt) throws org.codehaus.plexus.components.interactivity.PrompterException",
      "description": "Interactive feature of org.machanism.machai.gw.maven.ActMojo that reads multi-line prompt text from Maven's interactive prompter when an action string is not supplied directly through configuration.",
      "examples": [
        {
          "snippet": "mvn gw:act",
          "description": "How to use it: Step 1, run the action goal without -Dgw.act. Step 2, enter the action prompt when Maven asks for it. Step 3, finish the prompt input so the plugin can process the scanned files using your interactive instructions."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "name": "scanProjectClasses",
      "signature": "public void scanProjectClasses(org.apache.maven.project.MavenProject project)",
      "description": "Feature of org.machanism.machai.gw.maven.tools.ClassFunctionalTools that registers a Maven project by scanning and caching class metadata for later reflective lookup operations.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.maven.tools.ClassFunctionalTools tools = new org.machanism.machai.gw.maven.tools.ClassFunctionalTools();\ntools.scanProjectClasses(project);",
          "description": "How to use it: The plugin can initialize helper tools for the active Maven project so later AI-assisted class lookup requests can resolve project and dependency classes efficiently."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "name": "findClass",
      "signature": "public java.lang.String findClass(java.lang.String className, java.io.File projectDir)",
      "description": "Feature of org.machanism.machai.gw.maven.tools.ClassFunctionalTools that finds fully qualified class names whose simple names match a supplied regular expression within the registered Maven project context.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.maven.tools.ClassFunctionalTools tools = new org.machanism.machai.gw.maven.tools.ClassFunctionalTools(project);\njava.lang.String matches = tools.findClass(\".*Mojo\", project.getBasedir());",
          "description": "How to use it: Query the helper for classes such as GWMojo, ActMojo, or CleanMojo by matching simple class names with a regular expression."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "name": "getClassInfo",
      "signature": "public java.util.Map<java.lang.String,java.lang.Object> getClassInfo(java.lang.String className, java.io.File projectDir)",
      "description": "Feature of org.machanism.machai.gw.maven.tools.ClassFunctionalTools that returns reflective metadata for a requested class, including modifiers, superclass, interfaces, fields, constructors, methods, annotations, classpath origin, and dependency coordinates when available.",
      "examples": [
        {
          "snippet": "org.machanism.machai.gw.maven.tools.ClassFunctionalTools tools = new org.machanism.machai.gw.maven.tools.ClassFunctionalTools(project);\njava.util.Map<java.lang.String,java.lang.Object> info = tools.getClassInfo(\"org.machanism.machai.gw.maven.GWMojo\", project.getBasedir());",
          "description": "How to use it: Retrieve structured metadata for a plugin class so an AI-assisted workflow can reason about available members, annotations, and class origins."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "name": "findClasses",
      "signature": "public java.util.List<com.google.common.reflect.ClassPath.ClassInfo> findClasses(java.lang.String className)",
      "description": "Feature of org.machanism.machai.gw.maven.tools.ClassInfoHolder that finds loadable public or protected classes whose simple names match the supplied regular expression.",
      "examples": [
        {
          "snippet": "java.util.List<com.google.common.reflect.ClassPath.ClassInfo> matches = holder.findClasses(\".*Mojo\");",
          "description": "How to use it: Search the project-scoped class cache for plugin-related class names that match a regular expression pattern."
        }
      ]
    },
    {
      "package": "org.machanism.machai.gw.maven.tools",
      "name": "loadClass",
      "signature": "public java.lang.Class<?> loadClass(java.lang.String className) throws java.lang.ClassNotFoundException",
      "description": "Feature of org.machanism.machai.gw.maven.tools.ClassInfoHolder that loads a class by fully qualified name using a class loader assembled from the Maven project's classpath and output directories.",
      "examples": [
        {
          "snippet": "java.lang.Class<?> clazz = holder.loadClass(\"org.machanism.machai.gw.maven.GWMojo\");",
          "description": "How to use it: Resolve a project or dependency class dynamically after the holder has initialized project classpath information."
        }
      ]
    }
  ],
  "customizations": [
    {
      "name": "gw.model",
      "description": "Configuration property that selects the provider and model identifier passed to the Ghostwriter workflow, for example an OpenAI or other GenAI backend model string.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:gw -Dgw.model=openai:gpt-4o-mini",
          "description": "Choose the GenAI provider and model used during guided processing."
        }
      ]
    },
    {
      "name": "gw.path",
      "description": "Configuration property that overrides the default scan root. It is commonly used to point the plugin at documentation directories such as src/site instead of scanning the entire execution root or module base directory.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:gw-per-module -Dgw.path=src/site",
          "description": "Restrict processing to a module or project documentation directory."
        }
      ]
    },
    {
      "name": "gw.instructions",
      "description": "Configuration property that supplies additional instruction locations consumed by the workflow. These instructions complement embedded @guidance blocks.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:gw-per-module -Dgw.instructions=src/site/guidance.md",
          "description": "Provide a separate instruction source to refine Ghostwriter behavior during scanning and processing."
        }
      ]
    },
    {
      "name": "gw.excludes",
      "description": "Configuration property that defines patterns or paths to exclude during scanning, which is useful for skipping generated folders, dependencies, temporary outputs, or unrelated directories.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:gw-per-module -Dgw.excludes=target,node_modules",
          "description": "Prevent generated output and unrelated folders from being included in the scan."
        }
      ]
    },
    {
      "name": "genai.serverId",
      "description": "Configuration property that selects a Maven settings.xml server entry used to resolve GenAI credentials and optional provider-specific XML configuration values.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:gw -Dgenai.serverId=my-model-server",
          "description": "Load secure provider credentials from ~/.m2/settings.xml instead of hardcoding them in the project."
        }
      ]
    },
    {
      "name": "logInputs",
      "description": "Configuration property that controls whether the plugin logs the list of workflow input files before processing begins.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:act -DlogInputs=true",
          "description": "Enable additional runtime visibility for troubleshooting or auditing a processing run."
        }
      ]
    },
    {
      "name": "gw.threads",
      "description": "Configuration property specific to the gw:gw aggregator goal that enables or disables multi-threaded module processing.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:gw -Dgw.threads=true",
          "description": "Enable multi-threaded module processing for the aggregator goal."
        }
      ]
    },
    {
      "name": "gw.act",
      "description": "Configuration property used by action-oriented goals to provide the prompt text applied to scanned files. If omitted for gw:act, the plugin can ask for the text interactively.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:act -Dgw.act=\"Rewrite this documentation in a more concise style\"",
          "description": "Run a one-off prompt-driven documentation transformation from the command line."
        }
      ]
    },
    {
      "name": "gw.acts",
      "description": "Configuration property that points to a directory containing predefined action definitions used by action goals.",
      "type": "configuration property",
      "examples": [
        {
          "snippet": "mvn gw:act -Dgw.acts=src/site/acts",
          "description": "Resolve reusable action definitions from a dedicated directory instead of embedding every prompt directly in the command line."
        }
      ]
    }
  ],
  "studs": [],
  "examples": [
    {
      "title": "Install, configure, and run guided documentation processing with the GW Maven Plugin",
      "scenario": "Use the library as a ready-to-use Maven plugin component for AI-assisted guided documentation maintenance.",
      "steps": [
        "Step 1: Add the plugin to the build/plugins section of your pom.xml.",
        "Step 2: Add embedded @guidance blocks to the files you want Ghostwriter to process.",
        "Step 3: If your GenAI provider requires credentials, create a matching server entry in ~/.m2/settings.xml.",
        "Step 4: Choose a scan root such as src/site when you want to focus on documentation assets.",
        "Step 5: Run the gw:gw goal from the project root and review the updated files."
      ],
      "configuration": {
        "pomXml": "<build>\n  <plugins>\n    <plugin>\n      <groupId>org.machanism.machai</groupId>\n      <artifactId>gw-maven-plugin</artifactId>\n      <version>1.2.0</version>\n    </plugin>\n  </plugins>\n</build>",
        "settingsXml": "<settings>\n  <servers>\n    <server>\n      <id>my-model-server</id>\n      <username>your-username</username>\n      <password>your-password</password>\n    </server>\n  </servers>\n</settings>"
      },
      "commands": [
        "mvn gw:gw -Dgenai.serverId=my-model-server -Dgw.model=openai:gpt-4o-mini -Dgw.path=src/site"
      ],
      "description": "This practical how-to example shows how to install the plugin, configure secure credentials, focus processing on documentation files, and execute guided Ghostwriter automation from Maven."
    },
    {
      "title": "Run a one-off documentation rewrite with the action goal",
      "scenario": "Use the plugin to apply a concrete prompt-driven transformation to documentation files.",
      "steps": [
        "Step 1: Ensure the plugin is declared in pom.xml or invoke it by full coordinates.",
        "Step 2: Decide which directory to scan, for example src/site.",
        "Step 3: Provide a practical action prompt with -Dgw.act, such as rewriting headings or simplifying wording.",
        "Step 4: Execute the gw:act goal and inspect the changed files before committing them."
      ],
      "commands": [
        "mvn gw:act -Dgw.act=\"Rewrite headings for clarity\" -Dgw.path=src/site",
        "mvn gw:act -Dgw.acts=src/site/acts -DlogInputs=true"
      ],
      "description": "This example demonstrates a practical how-to workflow for prompt-driven documentation maintenance using the ready-to-use action goal."
    },
    {
      "title": "Process modules in standard Maven reactor order",
      "scenario": "Use the per-module guided processing goal in a multi-module Maven build.",
      "steps": [
        "Step 1: Open the execution-root directory of the multi-module build.",
        "Step 2: Configure provider credentials in ~/.m2/settings.xml if required.",
        "Step 3: Run gw:gw-per-module to process content module by module in standard reactor order.",
        "Step 4: Review the results for each module after Maven completes the build."
      ],
      "commands": [
        "mvn gw:gw-per-module -Dgw.path=src/site -Dgenai.serverId=my-model-server"
      ],
      "description": "This practical example shows when to choose the per-module goal instead of the aggregator goal in a Maven reactor build."
    },
    {
      "title": "Run reactor-aware action processing",
      "scenario": "Use the per-module action variant when a multi-module project should use standard reactor execution semantics.",
      "steps": [
        "Step 1: Start from the execution root of the Maven reactor.",
        "Step 2: Supply a concrete prompt with -Dgw.act or prepare reusable definitions with -Dgw.acts.",
        "Step 3: Run gw:act-per-module with an appropriate scan directory.",
        "Step 4: Inspect the updated content after the reactor build completes."
      ],
      "commands": [
        "mvn gw:act-per-module -Dgw.act=\"Normalize section titles\" -Dgw.path=src/site"
      ],
      "description": "This example provides a real-world how-to scenario for action-based processing in a standard Maven reactor context."
    },
    {
      "title": "Configure secure GenAI credentials with Maven settings.xml",
      "scenario": "Use Maven's standard server mechanism so secrets are not stored directly in the project.",
      "steps": [
        "Step 1: Add a server entry to ~/.m2/settings.xml containing your provider credentials and optional XML configuration.",
        "Step 2: Reference that server with -Dgenai.serverId when invoking the plugin.",
        "Step 3: Run a normal guided or action goal and let the plugin load the credentials into the runtime configurator."
      ],
      "configuration": {
        "settingsXml": "<settings>\n  <servers>\n    <server>\n      <id>my-model-server</id>\n      <username>your-username</username>\n      <password>your-password</password>\n      <configuration>\n        <AUTH_URL>https://example.invalid/auth</AUTH_URL>\n      </configuration>\n    </server>\n  </servers>\n</settings>"
      },
      "commands": [
        "mvn gw:gw -Dgenai.serverId=my-model-server -Dgw.model=openai:gpt-4o-mini"
      ],
      "description": "This how-to scenario focuses on secure credential resolution for local development and CI pipelines."
    },
    {
      "title": "Clean temporary Ghostwriter workflow artifacts",
      "scenario": "Use the plugin's maintenance goal to remove transient files created during guided processing.",
      "steps": [
        "Step 1: Run one or more guided or action-based plugin goals that create temporary workflow artifacts.",
        "Step 2: Execute mvn gw:clean from the project or module root.",
        "Step 3: Verify that temporary workflow files have been removed from the working directory."
      ],
      "commands": [
        "mvn gw:clean"
      ],
      "description": "This example shows the practical cleanup workflow for keeping the working tree free of temporary GW processing artifacts."
    }
  ],
  "dependencies": []
}