[docs] add workflow comments and simplify README to prevent staleness

- Add descriptive comments to key workflow files explaining purpose and triggers
- Simplify workflows README.md to focus on naming convention only
- Remove detailed workflow descriptions that can get out of date
- Point users to individual workflow files for current documentation

Addresses review feedback: documentation can get out of date quickly,
put comments into workflows themselves with single example in README.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/README.md

@@ -1,92 +1,21 @@
-# GitHub Workflows Documentation
+# GitHub Workflows
 
 ## Naming Convention
 
-All workflow files follow a consistent naming pattern for improved organization and discoverability.
-
-### File Naming Format
-
-```
-<prefix>-<descriptive-name>.yaml
-```
-
-**Rules:**
-1. Use `.yaml` extension consistently (not `.yml`)
-2. Use lowercase letters only
-3. Use hyphens (`-`) as word separators
-4. Start with a category prefix (see below)
-5. Follow prefix with a descriptive name that clearly indicates the workflow's purpose
+Workflow files follow a consistent naming pattern: `<prefix>-<descriptive-name>.yaml`
 
 ### Category Prefixes
 
-| Prefix | Category | Purpose | Example |
-|--------|----------|---------|---------|
-| `ci-` | Continuous Integration | Testing, linting, validation workflows | `ci-tests-e2e.yaml` |
-| `release-` | Release Management | Version bumps, release branches, release drafts | `release-version-bump.yaml` |
-| `ci-` | Continuous Integration | Testing, linting, validation workflows | `ci-tests-e2e.yaml` |
-| `release-` | Release Management | Version bumps, release branches, release drafts | `release-version-bump.yaml` |
-| `pr-` | PR Automation | PR-specific workflows triggered by labels or comments | `pr-claude-review.yaml` |
-| `types-` | Type Generation | TypeScript type generation and updates | `types-registry-api.yaml` |
-| `i18n-` | Internationalization | Locale and translation updates | `i18n-update-core.yaml` |
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| `ci-` | Testing, linting, validation | `ci-tests-e2e.yaml` |
+| `release-` | Version management, publishing | `release-version-bump.yaml` |
+| `pr-` | PR automation (triggered by labels) | `pr-claude-review.yaml` |
+| `types-` | TypeScript type generation | `types-registry-api.yaml` |
+| `i18n-` | Internationalization updates | `i18n-update-core.yaml` |
 
-## Workflow Organization
+## Documentation
 
-### Test Workflows (`ci-tests-*`)
-- `ci-tests-e2e.yaml` - End-to-end testing with Playwright
-- `ci-tests-unit.yaml` - Unit and component testing with Vitest
-- `ci-tests-storybook.yaml` - Storybook build and visual regression testing
-- `ci-tests-*-forks.yaml` - Fork-safe deployment workflows (deploy results without exposing secrets)
+Each workflow file contains comments explaining its purpose, triggers, and behavior. For specific details about what each workflow does, refer to the comments at the top of each `.yaml` file.
 
-### PR Label Workflows (`pr-*`)
-These workflows are triggered when specific labels are added to PRs:
-
-| Workflow | Trigger Label | Purpose |
-|----------|---------------|---------|
-| `pr-backport.yaml` | `needs-backport` | Cherry-pick PRs to release branches |
-| `pr-claude-review.yaml` | `claude-review` | AI-powered code review |
-| `pr-playwright-snapshots.yaml` | `New Browser Test Expectations` | Update visual test snapshots |
-
-## Workflow Triggers
-
-For more details on workflow triggers, see [GitHub's workflow trigger documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows).
-
-### Common Trigger Patterns
-
-| Trigger Type | Use Case | Example |
-|--------------|----------|---------|
-| `push` to main/master | Production CI/CD | Deploy to production |
-| `pull_request` | PR validation | Run tests, linting |
-| `workflow_dispatch` | Manual execution | On-demand deployments |
-| `repository_dispatch` | External triggers | API type updates |
-| `workflow_run` | Chain workflows | Fork deployments |
-| `schedule` | Periodic tasks | Nightly builds |
-| Label added | Conditional actions | Review requests, snapshots |
-
-### Branch Protection Patterns
-
-- **Main branches**: `main`, `master`
-- **Release branches**: `core/**`, `release/**`
-- **Development branches**: `dev/**`, `develop/**`
-- **Desktop branches**: `desktop/**`
-- **WIP exclusion**: `!**wip/**`, `!wip/**`
-
-## Best Practices
-
-1. **Consistency**: Always use the naming convention for new workflows
-2. **Documentation**: Update this README when adding new prefixes or patterns
-3. **Permissions**: Use minimal required permissions for security
-4. **Caching**: Leverage GitHub Actions cache for dependencies and build artifacts
-5. **Concurrency**: Use concurrency groups to prevent duplicate runs
-6. **Secrets**: Never hardcode secrets; use GitHub Secrets
-7. **Fork Support**: Consider fork limitations when designing workflows
-8. **Error Handling**: Include proper error handling and status checks
-9. **Reusability**: Use workflow_call for shared logic across workflows
-
-## External Dependencies
-
-- **Cloudflare Pages**: Deployment platform for previews and test reports
-- **Chromatic**: Visual regression testing for Storybook
-- **OpenAI API**: Translation generation for i18n workflows
-- **PyPI**: Python package distribution
-- **npm Registry**: TypeScript types distribution
-- **Claude API**: AI code review
+For GitHub Actions documentation, see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows).

.github/workflows/ci-json-validation.yaml

@@ -1,4 +1,4 @@
-name: CI - JSON Validation
+name: "CI: JSON Validation"
 
 on:
   push:

.github/workflows/ci-tests-e2e.yaml

@@ -1,5 +1,9 @@
 name: Tests E2E CI
 
+# End-to-end testing with Playwright across multiple browsers and configurations
+# Runs on main branches and PRs, skips WIP branches
+# Generates test reports and deploys them to Cloudflare Pages for review
+
 on:
   push:
     branches: [main, master, core/*, desktop/*]

.github/workflows/ci-tests-storybook.yaml

@@ -1,6 +1,8 @@
 name: Tests Storybook CI
 
-# - [Automate Chromatic with GitHub Actions • Chromatic docs]( https://www.chromatic.com/docs/github-actions/ )
+# Builds Storybook and runs visual regression testing via Chromatic
+# Deploys Storybook previews to Cloudflare Pages for PR review
+# Reference: https://www.chromatic.com/docs/github-actions/
 
 on:
   workflow_dispatch: # Allow manual triggering

.github/workflows/ci-tests-unit.yaml

@@ -1,5 +1,8 @@
 name: Tests Unit CI
 
+# Unit and component testing with Vitest
+# Runs on main branches and PRs, skips WIP branches
+
 on:
   push:
     branches: [main, master, dev*, core/*, desktop/*]

.github/workflows/i18n-update-core.yaml

@@ -1,5 +1,8 @@
 name: i18n Update Core
 
+# Generates and updates translations for core ComfyUI components using OpenAI
+# Runs manually or automatically on version-bump PRs to keep translations current
+
 on:
   # Manual dispatch for urgent translation updates  
   workflow_dispatch:

.github/workflows/pr-claude-review.yaml

@@ -1,5 +1,8 @@
 name: PR Claude Review
 
+# AI-powered code review triggered by adding the "claude-review" label to a PR
+# Provides comprehensive analysis of code changes, architecture, and security
+
 permissions:
   contents: read
   pull-requests: write

.github/workflows/release-version-bump.yaml

@@ -1,5 +1,8 @@
 name: Release Version Bump
 
+# Manual workflow to increment package version and create version commit
+# Supports semantic versioning (patch, minor, major) and pre-release versions
+
 on:
   workflow_dispatch:
     inputs: