Add CONTRIBUTING.md, AGENTS.md

and links to those from some tools we use, and some README updates
with it

Signed-off-by: Jakob Naucke <jnaucke@redhat.com>

Author: Jakob-Naucke

.cursor/rules/project.mdc

@@ -0,0 +1,4 @@
+---
+description: Core project conventions -- read AGENTS.md in the project root
+alwaysApply: true
+---

AGENTS.md

@@ -0,0 +1,33 @@
+# Project objective
+
+See [README](./README.md##trusted-execution-cluster-operator-trusted-cluster-operator).
+
+- **Success looks like**: With the operator deployed, all nodes in the cluster are attested from hardware to software.
+- **Non-goals**: Rely on OpenShift, see the [confidential-clusters](https://github.com/confidential-clusters/operator) downstream.
+
+# Architecture
+
+- Entry points: see [README](./README.md#repository-structure).
+- Integrations: [Trustee](https://github.com/confidential-containers/trustee), [compute-pcrs](https://github.com/trusted-execution-clusters/compute-pcrs), [clevis-pin-trustee](https://github.com/latchset/clevis-pin-trustee)
+
+# Conventions
+
+- See [CONTRIBUTING](./CONTRIBUTING.md).
+- Use `Assisted-by:` or `Generated-by`: in commit messages for AI-supported contributions.
+- Never commit real credentials; use env vars and local `.env` (gitignored) with synthetic values in docs.
+
+# Things that human users of agents should do
+
+and agents should suggest when they detect
+
+- Have a coherent goal per session
+- Read architecture, security-sensitive paths, performance-critical design, ambiguous product trade-offs
+
+# Things agents should do, but can get wrong
+
+- The operator's crate name is `operator`.
+- Use MCPs when available
+  - Prefer the MCP LSP over `grep`
+  - Prefer the k8s LSP over `kubectl`.
+- Reuse, and check for other uses of a similar pattern. When functionality can be moved out of a function for reuse, commit the generalization before the new use.
+- Include lint-compatible code style when writing, not as an afterthought.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+- [Sign off commits](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff)
+- [Sign commits cryptographically](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---gpg-signkey-id)
+- Limit commit subjects to 50 and messages to 72 characters.
+- Bisects should stay intact
+  - Linting should pass, so a new definition must be used in the same commit.
+  - When a change requires a change to a test, the changes should be in the same commit. On the contrary, a larger new test can be in a separate commit for easier review.
+- Add small changes to larger PRs in separate commits to ease review burden, but do not add them to already open PRs.
+- Use `cargo fmt`. Always perform `make lint clippy` before publishing when code is changed.
+  - Use an extra binding if this saves more than one (formatted) LOC, e.g.
+```rust
+let svc = ATTESTATION_KEY_REGISTER_SERVICE;
+self.create_certificate(svc, ATT_REG_CERT, ATT_REG_SECRET, issuer_name)
+    .await?;
+```
+over
+```rust
+self.create_certificate(
+    ATTESTATION_KEY_REGISTER_SERVICE,
+    ATT_REG_CERT,
+    ATT_REG_SECRET,
+    issuer_name,
+)
+.await?;
+```
+- When functionality is changed, perform `make test` and [integration test](./tests/README.md) at least with basic attestation.
+- Prepend your commit subject with a short focus area. Omit this when making general operator changes. Examples are `tests`, `tests/azure`, `rvs` (reference values)
+- Use [REUSE](https://reuse.software) comments for new files, or exclude in [REUSE.toml](./REUSE.toml) when not possible.

README.md

@@ -10,14 +10,29 @@ within the cluster.
 
 ## Repository Structure
 
--   `/api`: Defines the `TrustedExecutionCluster` Custom Resource Definition (CRD) and associated CRDs and RBAC definitions in Go. Also contains a program to generate a `TrustedExecutionCluster` CR and associated deployment.
+The operator relies on Rust crates for its functionality.
+
+### Operator components
+
 -   `/operator`: Contains the source code for the Kubernetes operator itself.
 -   `/register-server`: A server that provides Clevis PINs for key retrieval with random UUIDs.
 -   `/attestation-key-register`: A server that accepts attestation key registrations from VMs and creates AttestationKey resources.
 -   `/compute-pcrs`: A program to compute PCR reference values using the [compute-pcrs library](https://github.com/trusted-execution-clusters/compute-pcrs) and insert them into a ConfigMap, run as a Job.
+
+### Other crates
+
 -   `/lib`: Shared Rust definitions, including translated CRDs
+-   `/tests`: Non-unit tests, most rely on a cluster being available. Many of those also rely on a virtualization backend.
+-   `/test_utils`: Operator setup helpers and virtualization backends
+
+### Other components
+
+-   `/docs`, `/examples`
+-   `/api`: Defines the `TrustedExecutionCluster` Custom Resource Definition (CRD) and associated CRDs and RBAC definitions in Go. Also contains a program to generate a `TrustedExecutionCluster` CR and associated deployment.
 -   `/scripts`: Helper scripts for managing a local `kind` development cluster.
 -   `/config`: The default output directory for generated manifests. This directory is not checked into source control.
+-   `/tools`: Tracking tool versions for autoupdates
+-   `/must-gather`: for OpenShift CI
 
 ## Getting Started
 

REUSE.toml

@@ -2,7 +2,8 @@ version = 1
 
 [[annotations]]
 path = [
-  "README.md",
+  ".cursor/rules/*.mdc",
+  "*.md",
   "Cargo.lock",
   "go.sum",
   "PROJECT",