seqeralabs
diff --git a/‎.claude/README.md‎
Lines changed: 217 additions & 13 deletions b/‎.claude/README.md‎
Lines changed: 217 additions & 13 deletions
diff --git a/‎.github/scripts/classify-pr-type.sh‎
Lines changed: 43 additions & 0 deletions b/‎.github/scripts/classify-pr-type.sh‎
Lines changed: 43 additions & 0 deletions
diff --git a/‎.github/scripts/post-inline-suggestions.sh‎
Lines changed: 1 addition & 1 deletion b/‎.github/scripts/post-inline-suggestions.sh‎
Lines changed: 1 addition & 1 deletion
@@ -1,36 +1,240 @@
 # Claude Code Configuration
 
-This directory contains Claude Code configuration for the Seqera Platform documentation repository.
+This directory contains Claude Code agents, skills, and configuration for the Seqera Platform documentation repository.
 
-## Skills
+## Overview
+
+**What's in `.claude/`:**
+- **Agents** - Editorial review assistants that check documentation quality
+- **Skills** - Task-specific workflows for documentation automation
+- **Configuration** - Settings for CLI and GitHub Actions integration
 
-Skills are AI-powered workflows that help automate documentation tasks. Skills in this directory are available to:
+**Available to:**
 - Claude Code CLI users working on this project
-- Claude Desktop app (when this directory is in a synced project)
-- GitHub Actions workflows using the Claude API
+- Claude Desktop app (synced projects)
+- GitHub Actions workflows via Claude API
+
+## Skills
+
+Skills are AI-powered workflows that automate specific documentation tasks.
 
 ### openapi-overlay-generator
 
 Generates OpenAPI overlay files for Seqera Platform API documentation updates.
 
-**Use when**:
-
+**Use when:**
 - Analyzing Speakeasy comparison overlays
 - Generating operations, parameters, or schemas overlay files
 - Documenting new API endpoints or Platform version updates
 - Validating overlay files against documentation standards
 
-See `skills/openapi-overlay-generator/SKILL.md` for complete documentation.
+**Documentation:** See `skills/openapi-overlay-generator/SKILL.md`
+
+**Invocation:** `/openapi-overlay-generator`
+
+### review
+
+Runs comprehensive editorial reviews on documentation files or directories.
+
+**Use when:**
+- Pre-commit review of changed files
+- Directory-wide quality checks
+- Targeted review (voice-tone only, terminology only)
+
+**Invocation:**
+```bash
+/review <file-or-directory> [--profile=<profile>]
+```
+
+**Profiles:**
+- `quick` - Voice-tone and terminology only
+- `comprehensive` - All agents
+- `new-content` - Includes structure checks
+
+## Agents
+
+Agents are specialized editorial reviewers that check documentation for specific quality criteria. They run automatically in GitHub Actions on PRs or manually via `/review`.
+
+### voice-tone
+
+Ensures documentation uses second person, active voice, and present tense.
+
+**Configuration:** `.claude/agents/voice-tone.md`
+
+**Checks:**
+- Second person ("you") vs third person ("the user")
+- Active vs passive voice
+- Present vs future tense
+- Hedging language ("may", "might", "could")
+
+### terminology
+
+Enforces consistent product names, feature names, and formatting.
+
+**Configuration:** `.claude/agents/terminology.md`
+
+**Checks:**
+- Product names (Seqera Platform, Studios, Nextflow)
+- Feature terminology (drop-down, compute environment)
+- UI formatting (bold for buttons, backticks for code)
+- RNA-Seq capitalization
+
+**Special rules:**
+- Tower: Acceptable in legacy contexts
+- TowerForge: Always acceptable
+- drop-down: Always hyphenated
+
+### clarity
+
+Improves readability by flagging complex sentences and jargon.
+
+**Configuration:** `.claude/agents/clarity.md`
+
+**Status:** Currently disabled in workflows
+
+**Checks:**
+- Sentence length (>30 words)
+- Undefined jargon
+- Complex constructions
+- Missing prerequisites
+
+### punctuation
+
+Ensures consistent punctuation across documentation.
+
+**Status:** Not yet implemented as separate agent
+
+**Checks:**
+- Oxford commas
+- List punctuation
+- Quotation marks
+- Dash usage
+
+## GitHub Actions integration
+
+### Documentation review workflow
+
+**File:** `.github/workflows/docs-review.yml`
+
+**Triggers:**
+- Pull requests modifying `platform-*` directories
+- Manual workflow dispatch
+
+**How it works:**
+0. Validates bash script syntax (fails fast if scripts have errors)
+1. Classifies PR as "rename" or "content" type
+2. Runs agents based on PR type (rename PRs skip voice-tone & terminology)
+3. Posts up to 60 inline suggestions per PR
+4. Saves full report as downloadable artifact (30-day retention)
+
+**Outputs:**
+- Inline suggestions on specific lines (click to apply)
+- Comment with download link if >60 suggestions found
+- Summary report with PR type and agent status
+
+### Scripts
+
+**`.github/scripts/post-inline-suggestions.sh`**
+- Converts agent findings to GitHub inline suggestions
+- Posts via GitHub Review API
+
+**`.github/scripts/classify-pr-type.sh`**
+- Analyzes git diff to determine PR type
+- Outputs "rename" or "content" for workflow decisions
+
+## Agent output format
+
+Agents output structured suggestions:
+
+```
+FILE: path/to/file.md
+LINE: 42
+ISSUE: Brief description
+ORIGINAL: |
+exact original text
+SUGGESTION: |
+corrected text
+---
+```
+
+This format is parsed by `post-inline-suggestions.sh` and converted to GitHub's inline suggestion syntax.
 
 ## For contributors
 
+### Working with API documentation
+
 When working on API documentation:
-1. Claude Code will automatically detect and offer to use relevant skills
-2. Skills provide specialized knowledge about documentation standards and automation
-3. Skills include scripts and references that ensure consistency across API docs
+1. Claude Code automatically detects and offers relevant skills
+2. Skills provide specialized knowledge about documentation standards
+3. Skills include scripts ensuring consistency across API docs
+
+### Working with editorial content
+
+When working on documentation content:
+1. Open PR → Agents automatically review changes
+2. Review inline suggestions on affected lines
+3. Apply fixes individually or batch-apply multiple
+4. Re-run workflow manually from Actions tab if needed
+
+### Testing changes locally
+
+```bash
+# Test specific agent
+/review --profile=quick platform-enterprise_docs/quickstart.md
+
+# Review entire directory
+/review platform-cloud/docs/
+
+# Test skill
+/openapi-overlay-generator
+```
+
+## Development
+
+### Modifying agents
+
+1. Edit agent definition in `.claude/agents/<agent-name>.md`
+2. Test locally with `/review`
+3. Create PR (agents will review their own changes)
+4. Merge after approval
+
+### Adjusting suggestion limits
+
+Current limit: 60 inline suggestions per PR
+
+To change: Edit `.github/workflows/docs-review.yml` lines 268-284
+
+### Adding new agents
+
+1. Create `.claude/agents/<new-agent>.md`
+2. Add to `.github/workflows/docs-review.yml`
+3. Update documentation in `.claude/README.md` and `CLAUDE.md`
+4. Test on sample content
 
 ## Maintenance
 
-- Skills are version-controlled with the repository
+- Skills and agents are version-controlled with the repository
 - Updates to skills should be reviewed like any other code change
-- Test skill changes locally before committing
+- Test changes locally before committing
+- Monitor the **Actions** tab in GitHub for workflow issues
+- Artifacts auto-delete after 30 days
+
+## Architecture
+
+```
+.claude/
+├── README.md                    # This file
+├── agents/
+│   ├── voice-tone.md           # Agent definitions
+│   ├── terminology.md
+│   └── clarity.md
+└── skills/
+    └── openapi-overlay-generator/
+        └── SKILL.md
+```
+
+## Resources
+
+- **User Guide:** See `CLAUDE.md` in repository root
+- **Workflows:** See `.github/workflows/docs-review.yml`
+- **Scripts:** See `.github/scripts/`
@@ -0,0 +1,43 @@
+#!/bin/bash
+# Classifies PR as "rename" or "content" based on git diff analysis
+
+set -e
+
+BASE_REF=${1:-master}
+HEAD_REF=${2:-HEAD}
+
+# Get diff stats
+SUMMARY=$(git diff --summary "$BASE_REF...$HEAD_REF")
+DIFF=$(git diff --numstat "$BASE_REF...$HEAD_REF")
+
+# Count rename operations
+RENAME_COUNT=$(echo "$SUMMARY" | grep -c "rename" || true)
+
+# Count total changed files
+TOTAL_FILES=$(echo "$DIFF" | wc -l | tr -d ' ')
+
+# Count files with significant content changes (>10 lines added+deleted)
+CONTENT_CHANGES=$(echo "$DIFF" | awk '{if ($1+$2 > 10) print}' | wc -l | tr -d ' ')
+
+# Calculate rename ratio
+if [[ $TOTAL_FILES -gt 0 ]]; then
+  RENAME_RATIO=$((RENAME_COUNT * 100 / TOTAL_FILES))
+else
+  RENAME_RATIO=0
+fi
+
+# Classification logic:
+# - If >70% of files are renames AND <5 files have significant content changes: "rename"
+# - Otherwise: "content"
+
+if [[ $RENAME_RATIO -gt 70 ]] && [[ $CONTENT_CHANGES -lt 5 ]]; then
+  echo "rename"
+else
+  echo "content"
+fi
+
+# Debug output (appears in GitHub Actions logs)
+echo "  Rename count: $RENAME_COUNT" >&2
+echo "  Total files: $TOTAL_FILES" >&2
+echo "  Content changes: $CONTENT_CHANGES" >&2
+echo "  Rename ratio: ${RENAME_RATIO}%" >&2
@@ -68,7 +68,7 @@ create_review() {
         local comment_body="**${current_issue}**"$'\n\n'
         comment_body+='```suggestion'$'\n'
         comment_body+="${current_suggestion}"$'\n'
-        comment_body+'```'
+        comment_body+='```'
 
         # Add to comments JSON array
         comments=$(jq -n \