AI integration design and PR compliance prototype

README.md

@@ -25,6 +25,7 @@ Note OED is transitioning to mostly public design documents. The private DevDocs
 - [enhancementToGithubAction.md](./githubAction/enhancementToGithubAction.md): securing GitHub action information.
 - [timescaleDB/timescaleDB.md](./timescaleDB/timescaleDB.md): Information on efforts to investigate TimescaleDB usage in OED.
 - [infisicalIntegration/infisicalIntegration.md](./infisicalIntegration/infisicalIntegration.md): Instructions for how to utilize Infisical secrets management to store database passwords.
+- [aiIntegration/aiWorkflowCompliance.md](./aiIntegration/aiWorkflowCompliance.md): Documents OED AI usage guidance, issue-tracking recommendations, and the pull request compliance prototype.
 
 ## Information
 

aiIntegration/aiPolicyDraft.md

@@ -0,0 +1,75 @@
+**Open Energy Dashboard**
+
+# AI Usage Policy for Contributors - Draft
+
+## Enforcement
+
+If OED determines that a contribution did not follow this policy, OED will attempt to resolve the issue with the contributor. If that isn't possible, OED may take remedial action, which may include public disclosure as part of the project's permanent record. Contributors have the right to present their case and appeal a decision, using the same reporting channel described in [OED's Code of Conduct](https://github.com/OpenEnergyDashboard/OED/blob/development/CODE_OF_CONDUCT.md).
+
+## Purpose
+
+Open Energy Dashboard is a student-focused open-source project. Contributors may use AI tools as support, but AI tools do not replace human judgment, learning, testing, or responsibility. AI-assisted work must still follow OED’s normal contribution, licensing, documentation, testing, and review standards.
+
+This policy applies to AI-assisted code, documentation, tests, pull request text, issue comments, translations, and review comments submitted to OED.
+
+## Principle
+
+AI tools may assist a contribution as long as the human contributor fully understands, tests, and takes responsibility for what they submit, consistent with OED's standard contribution process. 
+
+AI output is only a starting point. The contributor must decide whether the output is correct, useful, and appropriate for OED. 
+
+## Reputable Tool Use 
+
+Contributors must use AI tools in good faith, making a reasonable effort to use ones that are reputable and unlikely to introduce unsafe or malicious output.
+
+## Required Disclosure
+
+Contributors must disclose AI use. The disclosure should include the AI tool used, how it was used, what part of the contribution it affected, and any other information the project should be aware of. The majority must come from the human contributor; if it does not, the contributor must disclose this and explain why. AI tools must not be listed as authors or co-authors.
+
+## Human Responsibility
+
+The human contributor(s) are fully responsible for all submitted work, including AI-assisted portions. AI tools may assist, but they are not responsible parties.
+
+If multiple people contributed to a pull request, each human contributor remains responsible for the parts they contributed and together those parts must account for the entire contribution, no part of a submission may lack an accountable contributor. The pull request submitter is responsible for making sure AI use is disclosed accurately for the contribution as a whole, and that at least one contributor has taken responsibility for all parts of the submitted code.
+
+**Before submitting, the contributor must confirm that they:**
+
+- reviewed and understood all AI-assisted output
+- can explain the submitted changes without relying on AI
+- confirmed that any packages, libraries, or dependencies referenced in AI-assisted output actually exist and are correct, and reviewed the change for security implications
+- checked that the output is accurate and not fabricated
+- confirmed that the contribution follows OED’s CLA and other OED project requirements, including having the rights needed to submit AI-assisted work under the CLA
+
+Using AI does not reduce contributor responsibility.
+
+## Data and Privacy Protection
+Contributors must not enter secrets, credentials, private keys, access tokens, private user data, non-public security information, private deployment details, or confidential OED information into AI tools. If in doubt about whether something is safe to share, ask a maintainer first. 
+
+## OED Workflow Requirements
+AI-assisted contributions must follow the same contribution, testing, documentation, licensing, technical, and review [requirements](https://github.com/OpenEnergyDashboard/OED/blob/development/CONTRIBUTING.md) as all other OED contributions. AI tools may assist contributors or reviewers, but they must not replace OED's required human review. 
+
+## Higher-Risk Changes
+Any AI-assisted change that a contributor or OED considers higher-risk may require additional explanation, information and review before accepting.
+
+## Student Learning 
+For issues labeled `i-good-first-issue`, AI use is limited to learning support, such as understanding concepts, error messages, documentation, or project context. AI must not generate or substantially implement the solution. Contributors must be able to explain the problem, the files changed, their solution approach, and how the work was verified.
+
+Students are welcome to do one \`i-good-first-issue\` but need to consult with the project before doing an additional one, to verify appropriate work.
+
+## Unacceptable uses
+
+**Do not submit:**
+
+- fabricated commands, test results, citations, screenshots, or explanations
+- large AI-generated rewrites that are not clearly scoped to an issue
+- fully automated or fully autonomous AI actions (pull requests, code, issues, or review replies) submitting without meaningful human involvement 
+
+## Maintainer Review
+
+Maintainers may ask how AI was used, request testing evidence, ask the contributor to explain their work, request revisions, or close AI-assisted work that is inaccurate, untested, unsupported, overly broad, or not understood by the contributor. Contributors should not submit AI-assisted work with these problems, as doing so creates an unreasonable review burden for maintainers.
+
+## Other resources
+
+Link to PR template
+
+Link to [aiUsageGuidance.md]

aiIntegration/aiUsageGuidance.md

@@ -0,0 +1,54 @@
+# AI Usage Guidance for Contributors
+
+*This document is informational and does not establish binding requirements. See the AI Usage Policy Draft for the governing rules.*
+
+## Principle
+
+AI tools are most appropriate when they support a contributor’s own understanding, judgment, and review. They are not appropriate when they replace the contributor’s work or produce a contribution that the contributor has not reviewed, tested where applicable, or cannot explain it yourself.
+
+Examples of appropriate supportive use include:
+
+- Understanding OED code or documentation
+- Brainstorming possible approaches
+- Debugging errors or explaining error messages
+- Drafting documentation or improving wording
+- Suggesting tests or edge cases
+- Summarizing issues or pull requests
+- Translation support
+- Self-review before submitting work
+
+## AI Tools
+
+As of July 2026, the following tools were reviewed against OED code and issues and found generally reputable, with reliable output quality:
+
+- GitHub Copilot / Microsoft Copilot
+- Anthropic Claude
+- OpenAI, including ChatGPT and OpenAI API models
+- Amazon Web Services AI tools, including Kiro
+- Google AI tools, including Gemini
+
+This list will change as tools evolve — untested tools aren't excluded; any tool used in good faith, per Reputable Tool Use, is acceptable.
+
+## Higher-Risk Changes
+
+Areas that often warrant extra care include:
+
+- Database migrations
+- Authentication
+- Authorization
+- Security
+- Unit conversions
+- Readings logic
+- Graphing calculations
+- Docker
+- CI
+- Dependencies
+- Production configuration
+
+This list is illustrative, not exhaustive — other areas may also require extra care.
+
+## Student Learning
+
+**Example of assistive use:** asking AI to explain an error message or an unfamiliar concept while you work through a good-first-issue yourself.
+
+**Example of generative use (not permitted here):** asking AI to write the fix or implementation for you.