📚 docs: move BDD_TAGS.md to features directory for better organization

- Moved BDD_TAGS.md from root to features/ directory
- Updated documentation to reflect new location
- Maintains comprehensive tag documentation

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

features/BDD_TAGS.md

@@ -0,0 +1,159 @@
+# BDD Test Tags Documentation
+
+This document describes the tagging system used in the dance-lessons-coach BDD tests for selective test execution.
+
+## Tag Categories
+
+### Feature Tags
+Used to categorize tests by feature area:
+- `@auth` - Authentication and user management tests
+- `@config` - Configuration and hot reloading tests  
+- `@greet` - Greeting service tests
+- `@health` - Health check and monitoring tests
+- `@jwt` - JWT secret rotation and retention tests
+
+### Priority Tags
+Used to categorize tests by importance:
+- `@smoke` - Basic smoke tests that verify core functionality
+- `@critical` - Critical path tests that must always pass
+- `@basic` - Basic functionality tests
+- `@advanced` - Advanced or edge case scenarios
+
+### Component Tags
+Used to categorize tests by system component:
+- `@api` - API endpoint tests
+- `@v2` - Version 2 API tests
+- `@database` - Database interaction tests
+- `@security` - Security-related tests
+
+## Usage Examples
+
+### Running Smoke Tests
+```bash
+# Run all smoke tests
+godog --tags=@smoke features/
+
+# Run smoke tests for specific feature
+godog --tags=@smoke features/auth/
+```
+
+### Running Critical Tests
+```bash
+# Run all critical tests
+godog --tags=@critical features/
+
+# Run critical health tests
+godog --tags=@critical,@health features/
+```
+
+### Running Feature-Specific Tests
+```bash
+# Run all auth tests
+godog --tags=@auth features/
+
+# Run v2 API tests
+godog --tags=@v2 features/
+```
+
+### Combining Tags
+```bash
+# Run smoke tests for auth and health features
+godog --tags=@smoke,@auth,@health features/
+
+# Run critical API tests
+godog --tags=@critical,@api features/
+```
+
+## Tagging Conventions
+
+1. **Feature tags** should be applied at the feature level
+2. **Priority tags** should be applied at the scenario level
+3. **Component tags** should be applied at the scenario level
+4. **Multiple tags** can be applied to a single scenario
+
+### Example Feature File
+```gherkin
+@health @smoke
+Feature: Health Endpoint
+  The health endpoint should indicate server status
+
+  @basic @critical
+  Scenario: Health check returns healthy status
+    Given the server is running
+    When I request the health endpoint
+    Then the response should be "{\"status\":\"healthy\"}"
+
+  @advanced @api
+  Scenario: Health check with authentication
+    Given the server is running with auth enabled
+    When I request the health endpoint with valid token
+    Then the response should be "{\"status\":\"healthy\"}"
+```
+
+## Test Execution Scripts
+
+### Feature-Specific Testing
+```bash
+# Test specific feature
+./scripts/test-feature.sh greet
+
+# Test with specific tags
+./scripts/test-by-tag.sh @smoke greet
+```
+
+### Tag-Based Testing
+```bash
+# Run smoke tests for all features
+./scripts/test-by-tag.sh @smoke
+
+# Run critical auth tests
+./scripts/test-by-tag.sh @critical auth
+```
+
+## CI/CD Integration
+
+### Smoke Test Pipeline
+```yaml
+- name: Run Smoke Tests
+  run: godog --tags=@smoke features/
+```
+
+### Critical Path Testing
+```yaml
+- name: Run Critical Tests
+  run: godog --tags=@critical features/
+```
+
+### Feature-Specific Testing
+```yaml
+- name: Test Auth Feature
+  run: ./scripts/test-feature.sh auth
+```
+
+## Best Practices
+
+1. **Tag consistently** - Apply tags consistently across similar scenarios
+2. **Prioritize tests** - Use priority tags to identify critical tests
+3. **Document tags** - Keep this documentation updated with new tags
+4. **Review tags** - Regularly review tag usage to ensure relevance
+5. **CI/CD optimization** - Use tags to optimize CI/CD pipeline execution times
+
+## Tag Reference
+
+| Tag | Purpose | Example Usage |
+|-----|---------|--------------|
+| `@smoke` | Smoke tests | `@smoke` on critical features |
+| `@critical` | Critical path | `@critical` on essential scenarios |
+| `@basic` | Basic functionality | `@basic` on standard scenarios |
+| `@advanced` | Advanced scenarios | `@advanced` on edge cases |
+| `@auth` | Authentication | `@auth` on auth features |
+| `@config` | Configuration | `@config` on config scenarios |
+| `@api` | API endpoints | `@api` on endpoint tests |
+| `@v2` | V2 API | `@v2` on version 2 tests |
+
+## Future Enhancements
+
+- **Performance tags** - `@fast`, `@slow` for performance categorization
+- **Environment tags** - `@ci`, `@local` for environment-specific tests
+- **Risk tags** - `@high-risk`, `@low-risk` for risk-based testing
+- **Automated tag validation** - Script to validate tag usage consistency