Merge dev to main

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,66 +1,59 @@
 name: "Bug Report"
-description: Report a bug to help us improve python-project-template.
+description: "Report a bug to help us improve python-project-template."
 labels: ["bug"]
+
 body:
   - type: markdown
     attributes:
-      value: |
-        Thank you for taking the time to report a bug!
-
-        For more information, please refer to our [Contribution Guide](https://github.com/danibcorr/python-project-template/blob/main/CONTRIBUTING.md).
+      value:
+        "Thank you for taking the time to report a bug!\n\nFor more information, please
+        refer to our [Contribution Guide](../CONTRIBUTING.md)."
 
   - type: textarea
     id: system-info
     attributes:
-      label: System Information
-      description: Please provide details about your system configuration.
-      placeholder: |
-        python-project-template version: 
-        Platform/OS: 
-        Python version: 
-        Backend:
+      label: "System Information"
+      description: "Please provide details about your system configuration."
+      placeholder:
+        "python-project-template version:\nPlatform/OS:\nPython version:\nBackend:"
     validations:
       required: true
 
   - type: textarea
     id: who-can-help
     attributes:
-      label: Who Can Help?
-      description: |
-        If you know the relevant maintainer, please tag them (e.g., @username). If not, leave blank and a core maintainer will assign it.
+      label: "Who Can Help?"
+      description:
+        "If you know the relevant maintainer, please tag them (e.g., @username). If not,
+        leave blank and a core maintainer will assign it."
       placeholder: "@Username ..."
 
   - type: checkboxes
     id: information-scripts-examples
     attributes:
-      label: Code Source
-      description: Where did the code causing the issue come from?
+      label: "Code Source"
+      description: "Where did the code causing the issue come from?"
       options:
         - label: "Official example scripts"
         - label: "My own modified scripts"
 
   - type: textarea
     id: reproduction
     attributes:
-      label: Steps to Reproduce
-      description: |
-        Provide a **minimal, reproducible example** with any relevant configuration. Use code blocks for formatting. Avoid screenshots as they can’t be easily copied.
-      placeholder: |
-        Steps to reproduce:
-        1.
-        2.
-        3.
-        Code snippet / Colab link:
-        ```python
-        # your code here
-        ```
+      label: "Steps to Reproduce"
+      description:
+        "Provide a minimal, reproducible example with any relevant configuration. Use
+        code blocks for formatting. Avoid screenshots as they can’t be easily copied."
+      placeholder:
+        "Steps to reproduce:\n1.\n2.\n3.\nCode snippet / Colab link:\n```python\n# your
+        code here\n```"
     validations:
       required: true
 
   - type: textarea
     id: expected-behavior
     attributes:
-      label: Expected Behavior
-      description: Clearly describe what you expected to happen.
+      label: "Expected Behavior"
+      description: "Clearly describe what you expected to happen."
     validations:
       required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -1,63 +1,56 @@
 name: "Feature Proposal"
-description: Suggest a new feature for python-project-template.
+description: "Suggest a new feature for python-project-template."
 labels: ["Feature request"]
+
 body:
   - type: textarea
     id: proposal-summary
     attributes:
-      label: Proposal Summary
+      label: "Proposal Summary"
       description:
         "Describe your proposal clearly. Include relevant information if available."
-      placeholder: |
-        Example:
-        - Type: Example
-        - Feature: New future to support
-        - Code: https://github.com/...
+      placeholder:
+        "Example:\n- Type: Example\n- Feature: New feature to support\n- Code:
+        https://github.com/..."
     validations:
       required: true
 
   - type: textarea
     id: motivation
     attributes:
-      label: Motivation
+      label: "Motivation"
       description:
         "Explain why this proposal is valuable. Is it solving a limitation or adding a
         unique advantage? If it's related to another GitHub issue, please link it."
-      placeholder: |
-        Example:
-        - Problem: ...
-        - Benefit: ...
+      placeholder: "Example:\n- Problem: ...\n- Benefit: ..."
     validations:
       required: true
 
   - type: checkboxes
     id: open-source-status
     attributes:
-      label: Open Source Status
+      label: "Open Source Status"
       description: "This helps assess implementation feasibility."
       options:
         - label: "Implementation code is available"
 
   - type: textarea
     id: useful-links
     attributes:
-      label: Useful Links & References
+      label: "Useful Links & References"
       description:
         "Provide additional resources or relevant repositories. Mention authors with
         @username if known."
-      placeholder: |
-        - Implementation repo: ...
-        - Paper link: ...
-        - Author: @gh-username
+      placeholder:
+        "- Implementation repo: ...\n- Paper link: ...\n- Author: @gh-username"
 
   - type: textarea
     id: contribution
     attributes:
-      label: Contribution Possibility
+      label: "Contribution Possibility"
       description:
-        "Can you help implement this? Please review the [Contribution
-        Guide](https://github.com/danibcorr/python-project-template/blob/main/CONTRIBUTING.md)
-        before offering code."
+        "Can you help implement this? Please review the Contribution Guide
+        (../CONTRIBUTING.md) before offering code."
       placeholder:
         "Yes, I can submit a PR / No, but I can help with testing / No, but I can help
         with design"

.gitignore

@@ -14,12 +14,16 @@ __pycache__/
 *.egg-info/
 .pytest_cache/
 *.ruff_cache/
+.cache
+.complexipy_cache/
 
 # Files
 *.pyc
 *.pyo
 *.pyd
 *.egg-info
+.python-version
+uv.lock
 
 # Exceptions
 !/.devcontainer/*

AGENTS.md

@@ -0,0 +1,59 @@
+# Agent Instructions
+
+This project is a **Cookiecutter template** used to generate new Python projects with a
+professional, ready-to-use structure. It integrates best practices for code quality,
+testing, security, documentation, and CI/CD. Because it is highly dynamic, it includes
+many optional settings and Jinja2 template blocks.
+
+## Getting Context
+
+Before interacting with the template, make sure to:
+
+1. **Review the README**: The `README.md` provides a high-level overview of the
+   template, its features, CI/CD workflow, and instructions to generate new projects.
+   Key features include:
+
+   - Linting & type checking (Ruff & Mypy)
+   - Security scanning (Bandit)
+   - Code complexity analysis (Complexipy)
+   - Testing (Pytest)
+   - Auto documentation (MkDocs + GitHub Pages)
+   - Preconfigured GitHub Actions for CI/CD
+
+2. **Review `AGENTS.md` in the generated project**: After generating a new project, the
+   template copies an `AGENTS.md` file to the project itself
+   (`{{cookiecutter.__package_slug}}/AGENTS.md`). This file provides project-specific
+   instructions for agents.
+
+## Working with the Template
+
+- **Jinja2 blocks**: Because this is a Cookiecutter template, many files contain Jinja2
+  template syntax. Agents should expect template variables like
+  `{{ cookiecutter.project_name }}` or conditional blocks.
+
+- **Testing functionality**:
+
+  - Create new projects inside the `workspaces/` directory.
+  - Run the Makefile targets to validate functionality:
+
+    - `make install` → installs dependencies
+    - `make pipeline` → runs linting, type checking, security analysis, complexity
+      checks, and tests
+    - `make all` → full workflow including documentation preview
+
+  - Ensure the environment is isolated (e.g., via `venv`) and that
+    [`uv`](https://github.com/astral-sh/uv) is installed to handle grouped dependency
+    installations.
+
+## Summary
+
+Agents interacting with this template should:
+
+- Understand it is a **dynamic project generator**, not a single static project.
+- Always use the generated `workspaces/` directory for testing.
+- Follow the Makefile workflow to validate and test features.
+- Keep track of optional components and ensure `post_gen_project.py` handles cleanup
+  properly.
+
+By following these instructions, agents will be able to safely generate, test, and
+maintain projects derived from this Python template.

README.md

@@ -29,6 +29,8 @@ professional foundation.
 - **Auto Documentation**: MkDocs + GitHub Pages for automated docs.
 - **CI/CD**: GitHub Actions automates linting, testing, and documentation deployment.
 
+And more.
+
 ## GitHub Actions
 
 The template includes a preconfigured GitHub Actions workflow that runs automatically on