Chore: add agents.md, update contributing guidelines

AGENTS.md

@@ -0,0 +1,36 @@
+# Guidance for AI agents
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before working on this repository, especially [Use of AI Tools](CONTRIBUTING.md#use-of-ai-tools). These contribution rules apply to all agent-assisted work.
+
+## Contribution boundaries
+
+- Do not open or submit pull requests, including "on behalf of" a human. The project does not accept PRs from AI agents. Prepare local changes for a human to review, verify, and submit personally.
+- The project does not accept PRs that are entirely or mostly AI-derived. Human submission and disclosure do not override this rule.
+- AI-generated content must be clearly disclosed as described in the contributing guidelines. When handing work back to a human, identify what was generated or changed with AI assistance so they can disclose it accurately.
+- Trust matters. Encourage first-time contributors to discuss their proposed change before preparing a PR, especially for large changes or changes involving AI-generated code. New features and enhancements should almost always target an existing feature request with community interest and discussion.
+- Issue reports must describe observed behavior, reproduction steps, and relevant logs. Do not add speculative root causes, code analysis, or proposed fixes to agent-generated reports.
+
+## Working on changes
+
+- Read the relevant code, tests, and documentation before editing. Paperless-ngx is complex: trace interactions between affected components rather than assuming a change is isolated.
+- Keep changes focused on the requested work and follow existing patterns. Avoid unrelated refactoring, formatting, dependency updates, or generated-file changes.
+- Consider effects on permissions, document processing, background tasks, storage, and the API when those areas are involved.
+- Add or update meaningful tests for behavior changes and regressions. Do not weaken tests or checks to make a change pass.
+- Update user or developer documentation when behavior or setup changes.
+- Keep credentials and private documents out of commits, fixtures, logs, and examples.
+
+## Repository and validation
+
+- `src/`: Django back end.
+- `src-ui/`: Angular front end, managed with `pnpm`.
+- `docs/`: Documentation.
+- `docker/` and `scripts/`: Deployment and development tooling.
+- Base functional changes on `dev`; documentation-only changes may target `main`.
+
+Follow [the development documentation](docs/development.md) for environment setup and testing. Common checks after setup are:
+
+- Back end: run `uv run pytest` from `src/` (use a test path to focus on the affected area).
+- Front end: run `pnpm test` and `pnpm lint` from `src-ui/`.
+- Formatting and other pre-commit checks: run `uv run prek run --files <changed-files>` from the repository root.
+
+When handing work back, summarize the changes, the checks actually run and their results, and any remaining uncertainty. Clearly state when a check could not be run; do not claim verification that did not happen. The human contributor must understand and independently verify the contribution before submitting it.

CONTRIBUTING.md

@@ -4,6 +4,12 @@ If you feel like contributing to the project, please do! Bug fixes and improveme
 
 ⚠️ Please note: Pull requests that implement a new feature or enhancement _should almost always target an existing feature request_ with evidence of community interest and discussion. This is in order to balance the work of implementing and maintaining new features / enhancements. Pull requests that are opened without meeting this requirement may not be merged.
 
+## Trust and collaboration
+
+Paperless-ngx places a high value on trust between contributors and maintainers. If you have not contributed before, consider starting with a discussion before preparing a pull request, especially for a large contribution or one involving AI-generated code.
+
+Paperless-ngx is complex, and understanding how its components interact takes time. A change that appears correct in isolation can have consequences elsewhere in the application. Contributors should understand the code they submit, explain how it fits into the project, and work with maintainers through review. Starting with smaller, focused contributions can help build that understanding and trust.
+
 If you want to implement something big:
 
 - As above, please start with a discussion! Maybe something similar is already in development and we can make it happen together.
@@ -61,9 +67,10 @@ This project does not specifically prohibit the use of AI tools or agents _durin
 
 1. Any content — code, pull request descriptions, issue reports or comments — that was generated in whole or in part by an AI tool or agent **must be clearly disclosed as such**. Failing to clearly disclose this is considered a violation of our [Code of Conduct](CODE_OF_CONDUCT.md) and may result in your contributions being closed and further action being taken.
 2. AI-generated code must not violate copyright protections.
-3. We will not accept PRs that are entirely or mostly AI-derived.
-4. Issue reports must describe _observed behavior only_: what happened, how to reproduce it and the relevant logs. Reports generated by an AI agent should not include code analysis, speculation about the root cause or suggest fixes.
-5. Contributors are responsible for everything they submit, regardless of how it was produced. Please do not open issues or PRs you have not verified yourself.
+3. We will not accept PRs opened or submitted by AI agents, including agents acting "on behalf of" a human. A human contributor must personally review, verify, and submit the contribution and take responsibility for it throughout review.
+4. We will not accept PRs that are entirely or mostly AI-derived.
+5. Issue reports must describe _observed behavior only_: what happened, how to reproduce it and the relevant logs. Reports generated by an AI agent should not include code analysis, speculation about the root cause or suggest fixes.
+6. Contributors are responsible for everything they submit, regardless of how it was produced. Please do not open issues or PRs you have not verified yourself.
 
 # Translating Paperless-ngx