📝 Update templated files

Author: mqt-app[bot]

.github/pull_request_template.md

@@ -6,7 +6,7 @@ List any dependencies that are required for this change.
 
 Fixes #(issue) <!--- Replace `(issue)` with the issue number fixed by this pull request. If this PR does not fix an issue, please remove this line. -->
 
-## Checklist:
+## Checklist
 
 <!---
 This checklist serves as a reminder of a couple of things that ensure your pull request will be merged swiftly.
@@ -20,3 +20,9 @@ This checklist serves as a reminder of a couple of things that ensure your pull
 - [ ] The changes follow the project's style guidelines and introduce no new warnings.
 - [ ] The changes are fully tested and pass the CI checks.
 - [ ] I have reviewed my own code changes.
+
+**If PR contains AI-assisted content:**
+
+- [ ] I have disclosed the use of AI tools in the PR description as per our [AI Usage Guidelines](https://github.com/munich-quantum-toolkit/qcec/blob/main/docs/ai_usage.md).
+- [ ] AI-assisted commits include an `Assisted-by: [Model Name] via [Tool Name]` footer.
+- [ ] I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

.github/renovate.json5

@@ -1,7 +1,7 @@
 {
   $schema: "https://docs.renovatebot.com/renovate-schema.json",
   suppressNotifications: ["prEditedNotification"],
-  minimumReleaseAge: '7 days',
+  minimumReleaseAge: "7 days",
   extends: [
     "config:recommended",
     ":gitSignOff",
@@ -14,78 +14,86 @@
     ":prConcurrentLimitNone",
     ":prHourlyLimitNone",
   ],
-  enabledManagers: ["cargo", "github-actions", "npm", "pep621", "pre-commit"],
+  enabledManagers: [
+    "cargo",
+    "github-actions",
+    "npm",
+    "pep621",
+    "pip_requirements",
+    "pre-commit",
+  ],
   lockFileMaintenance: {
     enabled: true,
-    automerge: true
+    automerge: true,
   },
   labels: ["dependencies"],
   schedule: ["every weekend"],
   packageRules: [
     {
       matchManagers: ["cargo"],
       addLabels: ["rust"],
-      commitMessagePrefix: "⬆\uFE0F\uD83E\uDD80"
+      commitMessagePrefix: "⬆\uFE0F\uD83E\uDD80",
     },
     {
       matchManagers: ["github-actions"],
       addLabels: ["github-actions"],
-      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC68\u200D\uD83D\uDCBB"
+      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC68\u200D\uD83D\uDCBB",
     },
     {
       matchManagers: ["npm"],
       addLabels: ["javascript"],
-      commitMessagePrefix: "⬆\uFE0F\uD83D\uDCDC"
+      commitMessagePrefix: "⬆\uFE0F\uD83D\uDCDC",
     },
     {
-      matchManagers: ["pep621"],
+      matchManagers: ["pep621", "pip_requirements"],
       addLabels: ["python"],
-      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC0D"
+      commitMessagePrefix: "⬆\uFE0F\uD83D\uDC0D",
     },
     {
       matchManagers: ["pre-commit"],
       addLabels: ["pre-commit"],
       commitMessagePrefix: "⬆\uFE0F\uD83E\uDE9D",
-      versioning: "pep440"
+      versioning: "pep440",
     },
     {
       matchUpdateTypes: ["lockFileMaintenance"],
       commitMessagePrefix: "⬆\uFE0F\uD83D\uDD12\uFE0F",
     },
     {
-      description: "Group and automerge all patch updates",
+      description: "Group and auto-merge all patch updates",
       groupName: "patch updates",
       matchUpdateTypes: ["patch"],
       matchCurrentVersion: "!/^0\.0/",
       commitMessagePrefix: "⬆\uFE0F\uD83E\uDE79",
-      automerge: true
+      automerge: true,
     },
     {
-      description: "Group and automerge all minor updates of stable dependencies (except our own packages)",
+      description: "Group and auto-merge minor updates of stable dependencies",
       groupName: "minor stable updates",
       matchUpdateTypes: ["minor"],
       matchCurrentVersion: "!/^0\./",
       matchPackageNames: [
         "!munich-quantum-toolkit/*",
         "!munich-quantum-software/*",
+        "!nanobind",
       ],
       commitMessagePrefix: "⬆\uFE0F\uD83E\uDE79",
-      automerge: true
+      automerge: true,
     },
     {
-      description: 'Disable minimum release age checks for our own GitHub Actions',
-      matchManagers: ['github-actions'],
+      description: "Disable minimum release age checks for our own GitHub Actions",
+      matchManagers: ["github-actions"],
       matchPackageNames: [
-        'munich-quantum-toolkit/*',
-        'munich-quantum-software/*',
+        "munich-quantum-toolkit/*",
+        "munich-quantum-software/*",
       ],
       minimumReleaseAge: null,
     },
     {
-      description: 'Disable minimum release age checks for our own Python packages',
-      matchDatasources: ['pypi'],
-      matchPackageNames: ['mqt*'],
+      description: "Disable minimum release age checks for our own Python packages",
+      matchDatasources: ["pypi"],
+      matchPackageNames: ["mqt*"],
       minimumReleaseAge: null,
-    }
-  ]
+    },
+  ],
 }

AGENTS.md

@@ -0,0 +1,97 @@
+<!--- This file has been generated from an external template. Please do not modify it directly. -->
+<!--- Changes should be contributed to https://github.com/munich-quantum-toolkit/templates. -->
+
+# MQT QCEC
+
+## C++
+
+- Configure: `cmake -S . -B build_cpp -DCMAKE_BUILD_TYPE=Release`
+- Build: `cmake --build build_cpp --config Release`
+- Test: `ctest --test-dir build_cpp -C Release`
+- Single test binary: `./build_cpp/test/path/to/binary`
+- For debug builds, replace `Release` with `Debug`.
+
+## Python
+
+- Set up build and test dependencies: `uv sync --inexact --only-group build --only-group test`
+- Install package without build isolation (fast rebuilds): `uv sync --inexact --no-dev --no-build-isolation-package mqt-qcec`
+- Run tests: `uv run --no-sync pytest`
+- Nox test shortcuts: `uvx nox -s tests`, `uvx nox -s minimums`
+- Python 3.14 variants: `uvx nox -s tests-3.14`, `uvx nox -s minimums-3.14`
+
+## Documentation
+
+- Sources: `docs/`
+- Build docs locally: `uvx nox --non-interactive -s docs`
+- Link check: `uvx nox -s docs -- -b linkcheck`
+
+## Tech Stack
+
+### General
+
+- `prek` for pre-commit hooks
+
+### C++
+
+- Targets Linux (glibc 2.28+), macOS (11.0+), and Windows on x86_64 and arm64 architectures
+- C++20
+- CMake 3.24+
+- `FetchContent` for dependency management (configured in `cmake/ExternalDependencies.cmake`)
+- `clang-format` and `clang-tidy` for formatting/linting (see `.clang-format` and `.clang-tidy`)
+- GoogleTest for unit tests (located in `test/`)
+
+### Python
+
+- Python 3.10+
+- Stable ABI wheels for 3.12+; free-threading support for 3.14+
+- `scikit-build-core` as build backend
+- `nanobind` for bindings
+- `uv` for installation, packaging, and tooling
+- `ruff` for formatting/linting (configured in `pyproject.toml`)
+- `ty` for type checking
+- `pytest` for unit tests (located in `test/python/`)
+- `nox` for task orchestration (tests, linting, docs)
+
+### Documentation
+
+- `sphinx`
+- MyST (Markdown)
+- Furo theme
+- `breathe` for C++ API docs
+
+## Development Guidelines
+
+### General
+
+- MUST run `uvx nox -s lint` after every batch of changes.
+  This runs the full `prek` hook set from `.pre-commit-config.yaml` (including `ruff`, `typos`, `ty`, formatting, and metadata checks).
+  All hooks must pass before submitting.
+- MUST add or update tests for every code change, even if not explicitly requested.
+- MUST follow existing code style by checking neighboring files for patterns.
+- MUST update `CHANGELOG.md` and `UPGRADING.md` when changes are user-facing, breaking, or otherwise noteworthy.
+- MUST include a commit footer attribution in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) if AI tools are used to prepare a commit.
+- NEVER modify files that start with "This file has been generated from an external template. Please do not modify it directly."
+  These files are managed by [the MQT templates action](https://github.com/munich-quantum-toolkit/templates) and changes will be overwritten.
+- PREFER running targeted tests over the full test suite during development.
+
+### C++
+
+- MUST use Doxygen-style comments.
+- MUST use `#pragma once` for header guards.
+- MUST regenerate stubs via `uvx nox -s stubs` when files in `bindings/` are added or modified.
+- NEVER edit `.pyi` files in `python/mqt/qcec/` manually; they are auto-generated by nanobind stubgen.
+- PREFER C++20 STL features over custom implementations.
+
+### Python
+
+- MUST use Google-style docstrings
+- PREFER running a single Python version over the full test suite during development.
+- PREFER fixing reported warnings over suppressing them (e.g., with `# noqa` comments for ruff); only add ignore rules when necessary and document why.
+- PREFER fixing typing issues reported by `ty` before adding suppression comments (`# ty: ignore[code]`); suppressions are sometimes necessary for incompletely typed libraries (e.g., Qiskit).
+
+## Self-Review Checklist
+
+- Did `uvx nox -s lint` pass without errors?
+- Are all changes covered by at least one automated test?
+- Were Python stubs regenerated via `uvx nox -s stubs` if bindings were modified?
+- Are `CHANGELOG.md` and `UPGRADING.md` updated when changes are user-facing, breaking, or otherwise noteworthy?

docs/ai_usage.md

@@ -0,0 +1,113 @@
+<!--- This file has been generated from an external template. Please do not modify it directly. -->
+<!--- Changes should be contributed to https://github.com/munich-quantum-toolkit/templates. -->
+
+# AI Usage Guidelines
+
+We acknowledge that AI tools (Large Language Models, code completion engines like GitHub Copilot, etc.) have become helpful assistants for many developers.
+We allow the use of these tools to assist with contributions, provided that their use is transparent, responsible, and that a **human remains in the loop** at all times.
+
+This guide outlines our policy on AI-assisted contributions to ensure code quality, maintainability, and legal compliance.
+
+## Core Principles
+
+### 1. You are Responsible
+
+**You are responsible for every line of code you submit.**
+
+Regardless of whether code was written by you or generated by an AI tool, you are the author and are fully accountable for the contribution. You must:
+
+- Fully understand the code you are submitting.
+- Be able to explain the reasoning behind the code and how it interacts with the rest of the codebase.
+- Verify that the code is correct, efficient, and follows our coding standards.
+
+**Do not blindly copy-paste AI-generated code.** If you cannot explain it, do not submit it.
+
+### 2. Human in the Loop
+
+> **Autonomous contributions from AI agents are not allowed.**
+
+When using AI tools, you must be the driver.
+The AI is the assistant.
+
+- **Review:** You must read and review all AI-generated code or text before submitting it.
+- **Edit:** AI-generated code often requires significant editing to meet project standards and correctness.
+- **Verify:** Ensure the code actually solves the problem and doesn't introduce subtle bugs or security vulnerabilities.
+
+### 3. Communication
+
+**Do not use AI tools to generate issue descriptions, pull request comments, or code reviews.**
+
+We value your personal input and communication.
+LLMs are notoriously unreliable and can produce "smart-sounding" but incorrect or irrelevant claims ("hallucinations").
+Phrase your communications in your own words.
+It is more important that we can follow your reasoning than that the text sounds "perfect".
+
+### 4. Transparency and Disclosure
+
+Transparency helps the community understand the role of these tools and develop best practices.
+
+**We encourage you to disclose any AI assistance.**
+This helps us understand how these tools are being used and identify potential issues.
+You can disclose this information in the following ways:
+
+- **Commit Messages**: Add a trailer to your commit message in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`)
+- **PR Description**: Mention the tool (name and version) and how it was used in the PR description.
+
+### 5. Licensing and Copyright
+
+You are responsible for ensuring that your contribution does not violate any third-party licenses or copyrights.
+
+- **Originality**: Your submission must be your own original work of authorship.
+- **Training Data**: Be aware that some AI tools may generate code that is substantially similar to their training data. You must ensure that you have the right to contribute the generated code under [our license](https://github.com/munich-quantum-toolkit/qcec/blob/main/LICENSE.md).
+
+## Extractive Contributions
+
+Processing pull requests and comments for MQT QCEC requires significant maintainer time and energy.
+Sending unreviewed AI output to open-source projects shifts the burden of verifying correctness from the contributor to the maintainer.
+We classify such contributions as "extractive" because they consume more community resources than they provide in value.
+
+Our **golden rule** is that a contribution should be valuable enough to justify the review effort.
+Nadia Eghbal captures this concept in her book _[Working in Public](https://press.stripe.com/working-in-public)_:
+
+> "When attention is being appropriated, producers need to weigh the costs and benefits of the transaction. To assess whether the appropriation of attention is net-positive, it's useful to distinguish between _extractive_ and _non-extractive_ contributions. Extractive contributions are those where the marginal cost of reviewing and merging that contribution is greater than the marginal benefit to the project's producers. In the case of a code contribution, it might be a pull request that's too complex or unwieldy to review, given the potential upside." — Nadia Eghbal
+
+Before AI tools became widespread, open-source project maintainers would often review all changes sent to the project simply because submitting a pull request was a sign of interest from a potential long-term contributor.
+However, AI tools now allow the rapid generation of large volumes of code, which can easily overwhelm maintainers if submitted without careful review.
+Our policy exists to ensure that maintainer time is spent on high-quality interactions rather than debugging AI-generated code.
+
+### Sustainable Open Source
+
+The Munich Quantum Toolkit (MQT) is committed to remaining free, open-source, and permissively licensed.
+We want to build a welcoming community where aspiring quantum software engineers can learn and grow.
+Reviewing contributions is a key part of this mentorship.
+
+However, to keep the project sustainable, we must prioritize non-extractive contributions.
+By thoroughly reviewing and understanding your AI-assisted code before submission, you ensure that your contribution is a net positive for the project.
+This helps us maintain a healthy ecosystem where both the software and its contributors can thrive.
+
+## Prohibited Uses
+
+- **"Good First Issues"**: Do not use AI tools to solve issues labeled as "good first issue". These are intended as learning opportunities for new contributors. Automating them defeats the purpose.
+- **Spam**: Do not use AI to generate low-quality or repetitive comments/reviews ("AI Slop").
+- **Unreviewed Code**: Submitting code that you, as a human, have not reviewed and tested yourself.
+
+## Summary
+
+We want to foster a welcoming community where developers can learn and grow. AI tools can be great for productivity, but they should not replace critical thinking or the learning process.
+If a maintainer judges that a contribution relies too heavily on unverified AI generation or lacks sufficient human understanding ("extractive contribution"), we may request that you revise it or close the PR.
+
+---
+
+Parts of this guide were inspired by or adapted from the contribution guidelines of
+
+- [Astral],
+- [Qiskit],
+- [LLVM], including the sources therein, such as [Fedora Council Policy Proposal: Policy on AI-Assisted Contributions (fetched 2026-03-12)][fedora], which is licensed under the [Creative Commons Attribution 4.0 International License][cca].
+
+with the help of Gemini 3 Pro (Preview). The links above serve as attribution.
+
+[Astral]: https://github.com/astral-sh/uv/blob/c89a78ec085077f6344b0439ddf07fdad7336310/CONTRIBUTING.md
+[Qiskit]: https://github.com/Qiskit/qiskit/blob/cd8701690723d3d9602fac63fe0bd7ea618799be/CONTRIBUTING.md#use-of-ai-tools
+[LLVM]: https://github.com/llvm/llvm-project/blob/9b6391f9c439c9926e8587b7b940e9a1e98a7819/llvm/docs/AIToolPolicy.md
+[fedora]: https://communityblog.fedoraproject.org/council-policy-proposal-policy-on-ai-assisted-contributions/
+[cca]: https://creativecommons.org/licenses/by/4.0/