docs: documentation overhaul

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing to reqstool-java-gradle-plugin
+
+Thank you for your interest in contributing!
+
+For DCO sign-off, commit conventions, and code review process, see the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md).
+
+## Prerequisites
+
+- Java 21+
+- Gradle 9.3+ (use the wrapper)
+
+## Setup
+
+```bash
+git clone https://github.com/reqstool/reqstool-java-gradle-plugin.git
+cd reqstool-java-gradle-plugin
+```
+
+## Build & Test
+
+```bash
+./gradlew build
+```

README.md

@@ -0,0 +1,55 @@
+[![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-gradle-plugin?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-java-gradle-plugin/pulse)
+[![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-java-gradle-plugin?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-gradle-plugin/issues)
+[![License](https://img.shields.io/github/license/reqstool/reqstool-java-gradle-plugin?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/)
+[![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-gradle-plugin/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-gradle-plugin/actions/workflows/build.yml)
+[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io)
+
+# Reqstool Gradle Plugin
+
+Gradle build plugin for [reqstool](https://github.com/reqstool/reqstool-client) that assembles requirements traceability artifacts.
+
+## Overview
+
+Collects `@Requirements` and `@SVCs` annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI. Supports Java 21+.
+
+## Installation
+
+Add the plugin to your `build.gradle`:
+
+```groovy
+plugins {
+    id 'io.github.reqstool.gradle-plugin' version '0.1.0'
+}
+
+requirementsTool {
+    datasetPath = file('docs/reqstool')
+}
+
+tasks.named('build') {
+    finalizedBy tasks.named('assembleRequirements')
+}
+
+tasks.named('assembleRequirements') {
+    dependsOn tasks.named('test')
+}
+```
+
+## Usage
+
+```bash
+gradle clean build
+```
+
+The plugin generates a ZIP artifact in `build/reqstool/` containing requirements, annotations, and test results.
+
+## Documentation
+
+Full documentation can be found [here](https://reqstool.github.io).
+
+## Contributing
+
+See the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT License.

docs/antora-playbook.yml

@@ -1,4 +1,5 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json
+# For local development only. Published site: https://reqstool.github.io
 
 site:
   title: Reqstool Gradle Plugin

docs/modules/ROOT/nav.adoc

@@ -1 +1,3 @@
-* xref:index.adoc[Start]
+* xref:index.adoc[Overview]
+* xref:configuration.adoc[Configuration]
+* xref:usage.adoc[Usage]

docs/modules/ROOT/pages/index.adoc

@@ -1,9 +1,62 @@
-= Reqstool Gradle Plugin
+= reqstool Gradle Plugin
 
-include::description.adoc[]
+This Gradle plugin generates a ZIP artifact containing combined annotations and various reports for reqstool. It provides zero-configuration defaults while allowing customization when needed.
 
-include::configuration.adoc[]
+== Features
 
-include::usage.adoc[]
+* *Zero-configuration*: Works out of the box with sensible defaults
+* *Automatic lifecycle integration*: Runs as part of the standard `build` task
+* *Maven publishing support*: Automatically registers ZIP artifact for publication
+* *Combines annotations*: Merges requirements annotations from implementation and test code
+* *Assembles ZIP artifact*: Creates structured ZIP containing requirements, test results, and configuration
 
-include::license.adoc[]
+== Quick Start
+
+== Apply the Plugin
+
+[source,gradle]
+----
+plugins {
+    id 'io.github.reqstool.gradle-plugin' version '0.1.0'
+}
+----
+
+== Default Behavior
+
+The plugin automatically:
+
+1. Runs after the `check` task (when tests complete)
+2. Combines annotation files from `build/generated-sources/` and `build/generated-test-sources/`
+3. Creates a ZIP artifact in `build/reqstool/` containing:
+   * `requirements.yml` (from `./reqstool/` directory)
+   * `software_verification_cases.yml` (optional)
+   * `manual_verification_results.yml` (optional)
+   * `annotations.yml` (combined/merged annotations)
+   * `test_results/` (XML test results from `build/test-results/`)
+   * `reqstool_config.yml` (configuration manifest)
+4. Registers the ZIP for Maven publication (if `maven-publish` plugin is applied)
+
+== Minimal Setup
+
+Create a `reqstool/` directory in your project root with a `requirements.yml` file:
+
+[source]
+----
+my-project/
+├── build.gradle
+├── reqstool/
+│   └── requirements.yml  (mandatory)
+└── src/
+----
+
+Run `gradle build` and the ZIP artifact will be created automatically.
+
+== Prerequisites
+
+* Gradle 9.0+
+* Java 21+
+* A `requirements.yml` file in the dataset directory (default: `./reqstool/`)
+
+== License
+
+MIT License.

docs/modules/ROOT/pages/usage.adoc

@@ -1,6 +1,6 @@
 == Usage
 
-To use the Reqstool Gradle Plugin, add the following configuration to your Gradle project's `build.gradle`:
+To use the reqstool Gradle Plugin, add the following configuration to your Gradle project's `build.gradle`:
 
 === Basic Usage