feat: Add comprehensive issue reporting and contribution guidelines (#105)

* feat: Add issue reporting guidelines to README.md

- Add dedicated "🐛 Issue Reporting" section with clear instructions
- Direct users to main repository issue tracker
- Include template for issue reporting with required information
- Improve project transparency and user support workflow

* fix: Update repository references and add issue reporting guidelines

- Fix incorrect repository reference (satwareAG-ironMike → satwareAG)
- Add comprehensive issue reporting section
- Clarify workflow between forks and main repository
- Improve contribution process documentation

* feat: Add GitHub issue templates for better issue management

- Add bug report template with structured fields
- Provide clear guidance for issue reporting
- Improve issue quality and processing efficiency

* feat: Add feature request template

- Add structured feature request template
- Include sections for use case, implementation details, and alternatives
- Improve feature planning and discussion process

* feat: Add content issue template

- Add template for content-related issues (typos, outdated info, etc.)
- Provide specific fields for content corrections
- Improve content quality maintenance process

* feat: Add issue template configuration

- Configure issue template chooser with clear options
- Add contact links for support and security
- Improve issue routing and user guidance

* feat: Add pull request template

- Add comprehensive PR template with structured sections
- Include checklist for quality assurance
- Improve code review and integration process

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,107 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior on satware.ai
+title: "[Bug]: "
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report a bug! This helps us improve satware.ai for everyone.
+        
+        Before submitting, please search existing issues to avoid duplicates.
+
+  - type: input
+    id: url
+    attributes:
+      label: Page URL
+      description: Where did you encounter this bug?
+      placeholder: https://satware.ai/path/to/page
+    validations:
+      required: true
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe what went wrong...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: Describe what should have happened...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      description: Which browser were you using?
+      options:
+        - Chrome
+        - Firefox
+        - Safari
+        - Edge
+        - Opera
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: browser-version
+    attributes:
+      label: Browser Version
+      description: What version of the browser were you using?
+      placeholder: e.g., Chrome 120, Safari 17.2
+
+  - type: dropdown
+    id: device-type
+    attributes:
+      label: Device Type
+      description: What type of device were you using?
+      options:
+        - Desktop
+        - Tablet
+        - Mobile
+        - Other
+
+  - type: input
+    id: device-info
+    attributes:
+      label: Device Information
+      description: Operating system and version
+      placeholder: e.g., Windows 11, macOS 14.2, iOS 17, Android 14
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here, including screenshots if applicable.
+      placeholder: Any additional information that might help us understand the issue...
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our Code of Conduct
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📧 General Support
+    url: mailto:info@satware.ai
+    about: For general inquiries and support questions
+  - name: 🔒 Security Report
+    url: mailto:security@satware.ai
+    about: Report security vulnerabilities privately
+  - name: 💬 Community Discussion
+    url: https://github.com/satwareAG/satware.ai/discussions
+    about: Ask questions and discuss ideas with the community

.github/ISSUE_TEMPLATE/content_issue.yml

@@ -0,0 +1,91 @@
+name: 📝 Content Issue
+description: Report issues with website content (typos, outdated information, etc.)
+title: "[Content]: "
+labels: ["content", "needs-review"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for helping improve our content! Every correction makes satware.ai better.
+        
+        Before submitting, please search existing issues to avoid duplicates.
+
+  - type: input
+    id: page-url
+    attributes:
+      label: Page URL
+      description: Which page has the content issue?
+      placeholder: https://satware.ai/path/to/page
+    validations:
+      required: true
+
+  - type: dropdown
+    id: issue-type
+    attributes:
+      label: Content Issue Type
+      description: What type of content issue is this?
+      options:
+        - Typo/Grammar Error
+        - Outdated Information
+        - Broken Link
+        - Missing Information
+        - Incorrect Information
+        - Unclear/Confusing Content
+        - Translation Error
+        - Formatting Issue
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: current-content
+    attributes:
+      label: Current Content
+      description: Copy and paste the problematic content (if applicable)
+      placeholder: Paste the current content that needs correction...
+
+  - type: textarea
+    id: suggested-correction
+    attributes:
+      label: Suggested Correction
+      description: How should the content be corrected?
+      placeholder: Provide your suggested correction...
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any additional context about the content issue
+      placeholder: |
+        - Why is this content incorrect/unclear?
+        - Do you have authoritative sources for the correction?
+        - Any other relevant details...
+
+  - type: input
+    id: section-location
+    attributes:
+      label: Section/Location
+      description: Where on the page is this content located?
+      placeholder: e.g., "Introduction section", "Step 3 of the tutorial", "Footer links"
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How significant is this content issue?
+      options:
+        - Low - Minor typo or formatting
+        - Medium - Affects understanding
+        - High - Misleading or significantly outdated
+        - Critical - Factually incorrect or potentially harmful
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our Code of Conduct
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,92 @@
+name: ✨ Feature Request
+description: Suggest a new feature or improvement for satware.ai
+title: "[Feature]: "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a new feature! Your ideas help shape the future of satware.ai.
+        
+        Before submitting, please search existing issues to avoid duplicates.
+
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: Feature Description
+      description: A clear and concise description of the feature you'd like to see.
+      placeholder: Describe the feature you're requesting...
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem-statement
+    attributes:
+      label: Problem or Use Case
+      description: What problem does this feature solve? What use case does it address?
+      placeholder: |
+        As a [type of user], I want [what] so that [why].
+        
+        Currently, I have to [current workaround] which is [problem with current approach].
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this feature to work?
+      placeholder: Describe your ideal solution...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or features?
+      placeholder: Describe any alternative solutions you've considered...
+
+  - type: dropdown
+    id: feature-type
+    attributes:
+      label: Feature Type
+      description: What type of feature is this?
+      options:
+        - Content Addition
+        - User Interface Improvement
+        - Navigation Enhancement
+        - Performance Optimization
+        - Accessibility Improvement
+        - Mobile Experience
+        - Search Functionality
+        - Integration
+        - Documentation
+        - Other
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      description: How important is this feature to you?
+      options:
+        - Low - Nice to have
+        - Medium - Would improve my experience
+        - High - Significant impact on usability
+        - Critical - Blocking my use of the site
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, mockups, or examples about the feature request here.
+      placeholder: Any additional information, examples, or mockups that might help us understand your request...
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our Code of Conduct
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,93 @@
+# Pull Request
+
+## 📝 Description
+
+<!-- Provide a brief description of the changes in this PR -->
+
+**What does this PR do?**
+
+- [ ] Add new content
+- [ ] Update existing content  
+- [ ] Fix bugs
+- [ ] Improve styling/design
+- [ ] Update documentation
+- [ ] Other: _____
+
+**Summary of changes:**
+<!-- Describe what you've changed/added/fixed -->
+
+## 🔗 Related Issues
+
+<!-- Link any related issues. Use "Fixes #123" to automatically close issues when PR is merged -->
+- Relates to #
+- Fixes #
+- Closes #
+
+## 🧪 Testing
+
+**How has this been tested?**
+
+- [ ] Tested locally with `./mkdocs.sh`
+- [ ] Tested in multiple browsers
+- [ ] Tested on mobile/tablet
+- [ ] Links verified
+- [ ] All pages load correctly
+- [ ] No broken functionality
+
+**Test environment:**
+- OS: 
+- Browser(s): 
+- Device type: 
+
+## 📸 Screenshots
+
+<!-- If applicable, add screenshots to help explain your changes -->
+
+**Before:**
+<!-- Screenshot of the current state (if applicable) -->
+
+**After:**
+<!-- Screenshot of your changes -->
+
+## ✅ Checklist
+
+**Before submitting this PR:**
+
+- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my changes
+- [ ] I have tested my changes locally
+- [ ] I have checked that all links work correctly
+- [ ] My changes generate no new warnings or errors
+- [ ] I have added/updated documentation if needed
+- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+
+**Content changes (if applicable):**
+
+- [ ] Content is accurate and up-to-date
+- [ ] Spelling and grammar are correct
+- [ ] Links are working and relevant
+- [ ] Images have appropriate alt text
+- [ ] Content follows the site's tone and style
+
+**Technical changes (if applicable):**
+
+- [ ] Code is properly formatted
+- [ ] No hardcoded values where configuration should be used
+- [ ] Changes are backward compatible
+- [ ] Performance impact has been considered
+
+## 💬 Additional Notes
+
+<!-- Add any additional context, concerns, or notes for reviewers -->
+
+## 📋 Reviewer Checklist
+
+<!-- For maintainers reviewing this PR -->
+
+- [ ] Changes are properly tested
+- [ ] Documentation is updated if needed
+- [ ] No breaking changes introduced
+- [ ] Security implications considered
+- [ ] Performance impact acceptable
+- [ ] Follows project conventions

CONTRIBUTING.md

@@ -2,49 +2,101 @@
 
 We welcome contributions to the `satware.ai` website! Your help is invaluable in making our documentation better. Please take a moment to review this document to understand how to contribute.
 
+## 🐛 Issue Reporting
+
+**Before contributing code**, please check if there's an existing issue for your concern:
+
+**🎯 [Check & Report Issues Here](https://github.com/satwareAG/satware.ai/issues)**
+
+### When to Report an Issue
+
+- Found a bug or error on the website
+- Have a feature request or suggestion
+- Experiencing technical difficulties
+- Notice inconsistencies in documentation
+
+### How to Report Issues
+
+When creating an issue, please include:
+
+1. **Clear, descriptive title**
+2. **Detailed description** of the problem or request
+3. **Steps to reproduce** (for bugs)
+4. **Expected vs. actual behavior**
+5. **Screenshots** (if applicable)
+6. **Browser/device information**
+7. **URL** where the issue occurs
+
+This helps our team address your concerns quickly and ensures no duplicate work.
+
 ## How to Contribute
 
-1.  **Fork the Repository**: Start by forking the `satwareAG-ironMike/satware.ai` repository to your GitHub account.
+### 1. Fork the Repository
+Start by forking the `satwareAG/satware.ai` repository to your GitHub account.
 
-2.  **Clone Your Fork**: Clone your forked repository to your local machine:
+### 2. Clone Your Fork
-    ```bash
+Clone your forked repository to your local machine:
-    git clone https://github.com/YOUR_USERNAME/satware.ai.git
+```bash
-    cd satware.ai
+git clone https://github.com/YOUR_USERNAME/satware.ai.git
-    ```
+cd satware.ai
+```
 
-3.  **Create a New Branch**: Create a new branch for your feature or bug fix. Use a descriptive name (e.g., `feature/add-new-page`, `fix/broken-link`):
+### 3. Create a New Branch
-    ```bash
+Create a new branch for your feature or bug fix. Use a descriptive name (e.g., `feature/add-new-page`, `fix/broken-link`):
-    git checkout -b feature/your-feature-name
+```bash
-    ```
+git checkout -b feature/your-feature-name
+```
 
-4.  **Set up Local Development**: Follow the "Local Development" instructions in the `README.md` to get the website running locally.
+### 4. Set up Local Development
-    ```bash
+Follow the "Local Development" instructions in the `README.md` to get the website running locally:
-    ./mkdocs.sh
+```bash
-    ```
+./mkdocs.sh
-    This will start a live-reloading server at `http://localhost:8000`.
+```
+This will start a live-reloading server at `http://localhost:8000`.
 
-5.  **Make Your Changes**:
+### 5. Make Your Changes
-    *   **Documentation**: Most content is written in Markdown files located in the `docs/` directory.
-    *   **Styling**: Custom styles are defined in `overrides/assets/css/custom.scss`. Changes to this file will be automatically compiled to `docs/assets/css/custom.css` by the `scss_watcher.py` script running in your Docker container.
-    *   **Configuration**: The main configuration is in `mkdocs.yml`.
 
-6.  **Test Your Changes**: Before submitting, ensure your changes work as expected by viewing them on your local development server.
+- **Documentation**: Most content is written in Markdown files located in the `docs/` directory.
+- **Styling**: Custom styles are defined in `overrides/assets/css/custom.scss`. Changes to this file will be automatically compiled to `docs/assets/css/custom.css` by the `scss_watcher.py` script running in your Docker container.
+- **Configuration**: The main configuration is in `mkdocs.yml`.
 
-7.  **Commit Your Changes**: Write clear and concise commit messages.
+### 6. Test Your Changes
-    ```bash
+Before submitting, ensure your changes work as expected by viewing them on your local development server.
-    git add .
-    git commit -m "feat: Add new section on AI agents"
-    ```
-    (Consider using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.)
 
-8.  **Push to Your Fork**:
+### 7. Commit Your Changes
-    ```bash
+Write clear and concise commit messages:
-    git push origin feature/your-feature-name
+```bash
-    ```
+git add .
+git commit -m "feat: Add new section on AI agents"
+```
+(Consider using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.)
 
-9.  **Create a Pull Request**: Go to your forked repository on GitHub and create a new Pull Request targeting the `main-mkdocs` branch of the `satwareAG-ironMike/satware.ai` repository.
+### 8. Push to Your Fork
-    *   Provide a clear title and description of your changes.
+```bash
-    *   Reference any related issues.
+git push origin feature/your-feature-name
+```
+
+### 9. Create a Pull Request
+Go to your forked repository on GitHub and create a new Pull Request targeting the `main-mkdocs` branch of the `satwareAG/satware.ai` repository.
+
+- **Provide a clear title and description** of your changes
+- **Reference any related issues** (e.g., "Fixes #123")
+- **Explain the impact** of your changes
+- **Include screenshots** for visual changes
+
+## Repository Workflow
+
+### Development Flow
+1. **Issues** are created and discussed in the main repository: `satwareAG/satware.ai`
+2. **Development** happens in individual forks
+3. **Pull Requests** are submitted to the main repository
+4. **Review and merge** happen in the main repository
+
+### Branch Strategy
+- **Main branch**: `main-mkdocs`
+- **Feature branches**: `feature/description`
+- **Bug fix branches**: `fix/description`
+- **Documentation branches**: `docs/description`
 
 ## Code of Conduct
 

README.md

@@ -94,6 +94,23 @@ The `satware.ai` website is automatically deployed to GitHub Pages.
 *   **SCSS Changes Not Reflecting**: Ensure the `scss_watcher.py` is running correctly within your Docker container. Check the Docker logs for any errors during SCSS compilation. The `scss_watcher.py` monitors `overrides/assets/css/custom.scss` and compiles it to `docs/assets/css/custom.css`.
 *   **Docker Issues**: If you encounter issues with the `./mkdocs.sh` script, verify that Docker is running and that you have the necessary permissions.
 
+## 🐛 Issue Reporting
+
+Found a bug, have a feature request, or experiencing issues with the satware.ai website? Please report all issues to our main repository:
+
+**🎯 [Report Issues Here](https://github.com/satwareAG/satware.ai/issues)**
+
+When reporting issues, please include:
+
+- **Clear description** of the problem or feature request
+- **Steps to reproduce** (if applicable)
+- **Expected behavior** vs actual behavior
+- **Browser/device information** (e.g., Chrome 120, Safari on iOS 17)
+- **Screenshots or error messages** (if relevant)
+- **URL** where the issue occurs (if specific to a page)
+
+This helps our team address your concerns quickly and effectively. We appreciate your feedback in making satware.ai better for everyone!
+
 ## 🤝 Contributing
 
 Contributions are welcome! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.