feat: Add CLI metadata extraction infrastructure and enrich-cli-help skill

.claude/README.md

@@ -0,0 +1,63 @@
+# Claude Code Configuration for Seqera Platform CLI
+
+This directory contains Claude Code configuration and skill documentation for contributors working on the Seqera Platform CLI codebase.
+
+## Skills Available
+
+### enrich-cli-help
+
+Workflow documentation for generating structured CLI metadata from the `tower-cli` source tree.
+
+**Use this skill when:**
+- Updating the metadata extractor
+- Validating metadata output
+- Reviewing the release-artifact workflow for CLI docs metadata
+
+**Quick start:**
+```bash
+./gradlew extractCliMetadata
+```
+
+This generates `build/cli-metadata/cli-metadata.json`.
+
+**Documentation:**
+- `skills/enrich-cli-help/SKILL.md` - Complete workflow guide
+- `skills/enrich-cli-help/README.md` - Quick reference
+
+## Project Context
+
+### Repository Structure
+```text
+tower-cli/
+├── src/main/java/io/seqera/tower/cli/
+│   └── utils/metadata/
+│       └── CliMetadataExtractor.java
+├── docs/
+│   └── README.md
+├── .claude/
+└── build.gradle
+```
+
+### Key Files
+
+- `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java`
+- `build.gradle`
+- `docs/README.md`
+- `.github/workflows/build.yml`
+
+## Workflow Overview
+
+```text
+1. Extract metadata
+   └─> ./gradlew extractCliMetadata
+   └─> Outputs build/cli-metadata/cli-metadata.json
+
+2. Verify
+   └─> Run tests when the extractor changes
+   └─> Confirm metadata shape stays stable
+
+3. Release
+   └─> Generate cli-metadata.json in CI
+   └─> Upload it to GitHub release assets
+   └─> Dispatch docs automation with the release asset URL
+```

.claude/skills/enrich-cli-help/README.md

@@ -0,0 +1,36 @@
+# CLI Metadata Generation Skill
+
+This skill documents how to generate and validate structured CLI metadata from the `tower-cli` source tree.
+
+## Quick Start
+
+Run:
+
+```bash
+./gradlew extractCliMetadata
+```
+
+The output is written to `build/cli-metadata/cli-metadata.json`.
+
+## What This Skill Does
+
+1. Generates CLI metadata from picocli command definitions
+2. Verifies the extractor output shape
+3. Documents the release-artifact workflow
+4. Keeps metadata generation independent from external OpenAPI specs
+
+## Release strategy
+
+- Metadata is generated from source code without modifying it
+- Metadata is a build and release artifact, not a tracked repository file
+- Downstream docs tooling should consume the release asset
+
+## Files
+
+- `SKILL.md` - Complete skill documentation
+
+## Requirements
+
+- Repository root: `tower-cli`
+- Gradle task: `extractCliMetadata`
+- Extractor: `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java`

.claude/skills/enrich-cli-help/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: enrich-cli-help
+description: Generate structured CLI metadata from tower-cli source code using the built-in Java extractor. Use when validating metadata generation, updating release automation, or checking the downstream artifact consumed by docs tooling.
+---
+
+# CLI Metadata Generation for Seqera Platform CLI
+
+This skill is for generating and validating CLI metadata from the `tower-cli` source tree.
+
+## When to Use This Skill
+
+Use this skill when:
+- Updating the metadata extractor implementation
+- Verifying that the Gradle task still produces valid metadata
+- Reviewing release automation for the metadata artifact
+- Investigating command coverage in the generated metadata
+- Confirming downstream docs consumers can rely on the release artifact
+
+## Scope
+
+The generator is deterministic and works directly from the compiled CLI command tree. It does not edit CLI source code and it does not depend on external OpenAPI specifications.
+
+## Workflow
+
+### Step 1: Generate metadata locally
+
+Run the Gradle task from the repository root:
+
+```bash
+./gradlew extractCliMetadata
+```
+
+The generated file is written to:
+
+```text
+build/cli-metadata/cli-metadata.json
+```
+
+### Step 2: Validate the output
+
+Check that the JSON contains the expected top-level keys:
+
+```text
+metadata
+hierarchy
+commands
+```
+
+If you are changing the extractor, add or update unit tests under `src/test/`.
+
+### Step 3: Review only the metadata generation path
+
+Focus on:
+- `src/main/java/io/seqera/tower/cli/utils/metadata/CliMetadataExtractor.java`
+- `build.gradle`
+- release automation in `.github/workflows/`
+- docs describing metadata generation
+
+Do not mix this workflow with CLI help-text enrichment or external API specs.
+
+### Step 4: Release behavior
+
+At release time the metadata should be:
+1. generated from the current `tower-cli` source tree
+2. uploaded as a GitHub release artifact
+3. passed to downstream docs tooling via the release asset URL
+
+## Notes
+
+- Remove hard-coded local paths from all documentation.
+- Keep generated metadata out of Git.
+- Prefer battle-tested libraries already on the classpath over hand-written serializers.
+- Keep the workflow focused on metadata generation only.

.github/pull_request_template.md

@@ -0,0 +1,55 @@
+## Description
+
+<!-- Provide a brief description of the changes in this PR -->
+
+## Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Performance improvement
+- [ ] Test updates
+
+## Changes Made
+
+<!-- List the main changes made in this PR -->
+
+-
+-
+-
+
+## Testing
+
+<!-- Describe the testing you've done -->
+
+- [ ] Tested locally
+- [ ] Added/updated unit tests
+- [ ] Added/updated integration tests
+- [ ] Manual testing performed
+
+## Pre-Merge Checklist
+
+<!-- Complete these items before merging -->
+
+- [ ] Code follows the project's style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex/non-obvious code
+- [ ] Documentation updated (if applicable)
+- [ ] No new warnings generated
+- [ ] Tests pass locally
+- [ ] Ran `./gradlew extractCliMetadata` if this PR changes the metadata extractor or release metadata workflow
+
+## Related Issues
+
+<!-- Link related issues using #issue_number -->
+
+Fixes #
+Related to #
+
+## Additional Notes
+
+<!-- Any additional information that reviewers should know -->

.github/workflows/build.yml

@@ -355,13 +355,42 @@ jobs:
             echo "VERSION=$VERSION"
             echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
 
+      - name: Generate CLI metadata artifact
+        run: ./gradlew extractCliMetadata
+        env:
+          GITHUB_USERNAME: ${{ github.actor }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Run JReleaser
         uses: jreleaser/release-action@v2
         env:
           JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           JRELEASER_HOMEBREW_GITHUB_TOKEN: ${{secrets.GH_JRELEASER_TOKEN}}
           JRELEASER_PROJECT_VERSION: ${{ steps.version.outputs.VERSION }}
 
+      - name: Upload CLI metadata to GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "v${{ steps.version.outputs.VERSION }}" build/cli-metadata/cli-metadata.json --clobber
+
+      - name: Dispatch docs update
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.DOCS_REPO_PAT }}
+          repository: seqera/docs
+          event-type: cli-release
+          client-payload: |
+            {
+              "cli_version": "${{ steps.version.outputs.VERSION }}",
+              "release_tag": "v${{ steps.version.outputs.VERSION }}",
+              "release_url": "https://github.com/${{ github.repository }}/releases/tag/v${{ steps.version.outputs.VERSION }}",
+              "metadata_url": "https://github.com/${{ github.repository }}/releases/download/v${{ steps.version.outputs.VERSION }}/cli-metadata.json",
+              "metadata_exists": true,
+              "repository": "${{ github.repository }}",
+              "sender": "${{ github.actor }}"
+            }
+
       - name: JReleaser release output
         if: always()
         uses: actions/upload-artifact@v4

.gitignore

@@ -5,9 +5,15 @@
 # Ignore Gradle build output directory
 build
 **/build-info.properties
+docs/cli-metadata.json
 
 # Location for unshared files
 .user/
 .DS_Store
 
+
 *.iml
+
+# macOS system files
+.DS_Store
+**/.DS_Store

build.gradle

@@ -151,6 +151,19 @@ tasks.register('runReflectionConfigGenerator', JavaExec) {
     jvmArgs = ["-agentlib:native-image-agent=access-filter-file=conf/access-filter-file.json,config-merge-dir=conf/"]
 }
 
+task extractCliMetadata(type: JavaExec) {
+    group = 'documentation'
+    description = 'Extract CLI metadata from the source tree using picocli metadata inspection'
+    classpath = sourceSets.main.runtimeClasspath
+    mainClass = 'io.seqera.tower.cli.utils.metadata.CliMetadataExtractor'
+    args = [file('build/cli-metadata/cli-metadata.json').absolutePath]
+    outputs.file(file('build/cli-metadata/cli-metadata.json'))
+    dependsOn classes
+    doFirst {
+        file('build/cli-metadata').mkdirs()
+    }
+}
+
 tasks.named('shadowJar') {
     archiveBaseName.set('tw')
     archiveClassifier.set('')