docs: Add detailed CI/CD workflow examples to CLAUDE.md

- Add 'How to trigger' sections with exact git commands for each pipeline
- Include practical examples: feature testing, contract publishing, releases
- Add 'Common CI/CD Workflows' section with real-world scenarios
- Document emergency rollback procedure
- Clarify contract-only service names (telegram_listener vs telegram-listener)

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

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

CLAUDE.md

@@ -179,39 +179,158 @@ This eliminates NuGet warning NU1507 and ensures consistent package resolution a
 The project uses Drone CI with 5 specialized pipelines:
 
 ### 1. Feature Validation (`feature/*`, `fix/*` branches)
-- Triggered on push to feature/fix branches
+**Purpose**: Test feature branches before merging to main
+
+**How to trigger**:
+```bash
+# Create feature branch and push
+git checkout -b feature/my-new-feature
+# ... make changes ...
+git add .
+git commit -m "Add new feature"
+git push origin feature/my-new-feature
+```
+
+**What happens**:
 - Runs build + tests with Testcontainers support
 - Provides fast feedback before merge
 - Duration: ~3-5 minutes
 
 ### 2. Main Validation (`main` branch)
-- Triggered on push to main
+**Purpose**: Ensure main branch stays healthy after merge
+
+**How to trigger**:
+```bash
+# Merge feature to main
+git checkout main
+git merge feature/my-new-feature
+git push origin main
+```
+
+**What happens**:
 - Same checks as feature validation
-- Ensures main branch stays healthy
+- Ensures main branch builds and tests pass
 - Duration: ~3-5 minutes
 
-### 3. Contracts-Only Publish (tags with `contracts_only:`)
+### 3. Contracts-Only Publish
-- Triggered by tag + commit message containing `contracts_only:<service>`
+**Purpose**: Publish NuGet contracts without building Docker images (fast iteration)
-- Publishes NuGet contracts without building Docker images
+
-- Fast iteration on contract changes
+**How to trigger**:
+```bash
+# Update contracts in a submodule
+cd telegram-listener
+# ... update Async.Api.Contracts ...
+git add . && git commit -m "Add MessageEdited event"
+git push
+
+# From parent repo, tag with contracts_only marker
+cd ..
+git add telegram-listener
+git commit -m "contracts_only:telegram_listener - Add MessageEdited event"
+git tag 0.7.41
+git push && git push --tags
+```
+
+**What happens**:
+- Publishes only the specified service's NuGet contracts
+- Skips Docker image builds
 - Duration: ~2 minutes
-- Example: `git commit -m "contracts_only:telegram_listener - Add MessageEdited event"`
 
-### 4. Full Release (clean tags)
+**Services**: `telegram_listener`, `text_matcher`, `users`
-- Triggered by tag without special markers
+
-- Complete release cycle:
+### 4. Full Release
-  1. Publish all NuGet contracts (parallel)
+**Purpose**: Complete release - contracts + images + deployment
-  2. Build all Docker images with Kaniko (parallel, after contracts)
+
-  3. Deploy to Kubernetes (automatic for `v*` tags)
+**How to trigger**:
+```bash
+# Make your changes, commit to main
+git add .
+git commit -m "Implement new feature"
+git push
+
+# Tag for full release (no special markers in commit message)
+git tag v1.3.0
+git push --tags
+```
+
+**What happens**:
+1. Publishes all NuGet contracts (parallel)
+2. Builds all Docker images with Kaniko (parallel, after contracts)
+3. Deploys to Kubernetes (automatic for `v*` tags)
 - Duration: ~8-10 minutes
-- Example: `git tag v1.3.0`
 
-### 5. Deploy-Only (tags with `deploy_only:`)
+### 5. Deploy-Only
-- Triggered by tag + commit message containing `deploy_only:`
+**Purpose**: Deploy existing images without rebuilding (rollbacks, hotfixes)
-- Skips building, only deploys existing images
+
-- Useful for rollbacks and hotfixes
+**How to trigger**:
+```bash
+# Deploy already-built images (e.g., rollback to previous version)
+git commit --allow-empty -m "deploy_only: Rollback to v1.2.9"
+git tag deploy-v1.2.9
+git push && git push --tags
+
+# Or deploy latest images
+git commit --allow-empty -m "deploy_only: Deploy latest"
+git tag deploy-latest
+git push && git push --tags
+```
+
+**What happens**:
+- Skips building entirely
+- Deploys specified tag's images (or `latest`)
 - Duration: ~1 minute
-- Example: `git commit --allow-empty -m "deploy_only: Deploy v1.2.9"`
+
+## Common CI/CD Workflows
+
+### Test a Feature Branch
+```bash
+git checkout -b feature/add-logging
+# ... make changes ...
+git add . && git commit -m "Add structured logging"
+git push origin feature/add-logging
+# ✅ Drone runs feature-validation pipeline
+```
+
+### Publish Contracts After API Changes
+```bash
+cd text-matcher
+# Update Nocr.TextMatcher.Async.Api.Contracts
+git add . && git commit -m "Add UserDeleted event"
+git push
+
+cd ..
+git add text-matcher
+git commit -m "contracts_only:text_matcher - Add UserDeleted event"
+git tag 0.8.5
+git push && git push --tags
+# ✅ Drone publishes text-matcher contracts to NuGet
+```
+
+### Full Release Workflow
+```bash
+# Work on main branch
+git add .
+git commit -m "Implement payment processing"
+git push
+# ✅ Drone runs main-validation
+
+# Tag for release
+git tag v2.0.0
+git push --tags
+# ✅ Drone runs full-release pipeline:
+#    1. Publishes all contracts
+#    2. Builds all Docker images
+#    3. Deploys to Kubernetes
+```
+
+### Emergency Rollback
+```bash
+# Rollback to last known good version
+git commit --allow-empty -m "deploy_only: Emergency rollback to v1.9.5"
+git tag rollback-v1.9.5
+git push && git push --tags
+# ✅ Drone deploys v1.9.5 images immediately (~1 minute)
+```
 
 ### Deployment Scripts