add AGENTS.md and a basic readme for the SDK

.github/pull_request_template.md

@@ -1,8 +1,6 @@
 <!--
-
 Thanks for creating a pull request!
 If this is your first time, please make sure to review CONTRIBUTING.md.
-
 -->
 
 ## Summary

AGENTS.md

@@ -0,0 +1,31 @@
+# AI Agent Configuration
+
+## Development
+
+* Use `make imports` before committing any change to Go code.
+* Use `go mod tidy` after any change to a `go.mod`.
+* Run `make lint` and fix all reported issues before submitting a pull request.
+* Run the e2e tests before submitting a pull request.
+* When possible, try to keep pull requests small and self-contained to make reviews easier. Follow
+  the repository's `.github/pull_request_template.md` and make sure to focus more on the reasons,
+  background and encountered problems that motivated the change and less on reiterating code
+  changes.
+
+## Documentation
+
+* Lines in Markdown files should not exceed 100 characters (use explicit line breaks).
+
+## Testing Instructions
+
+* Use `make clean build test-e2e` for running e2e tests.
+* To run a specific test package, use the `WHAT` environment variable, like
+  `WHAT=./test/e2e/apiexport make test-e2e`, or the `TEST_FLAGS` variable like
+  `TEST_FLAGS="-v -run NameOfTheTestFunction" make test-e2e`.
+
+## Changelogs
+
+* When generating a changelog for a new release, group all relevant pull requests based on their
+  `kind/...` label. Output these groups in descending order of importance.
+* Only include pull requests in the changelog that have a `release-note` block in their descriptions
+  on GitHub that is not empty or `NONE`.
+* List each pull request in the following form: `#<number>: <release note> (by @<author>)`

sdk/README.md

@@ -0,0 +1,48 @@
+# API Sync-Agent SDK
+
+This directory contains the syncagent's SDK: re-usable Go API types and generated functions for
+integrating the syncagent into 3rd-party applications.
+
+## Usage
+
+To install the SDK, simply `go get` it:
+
+```bash
+go get github.com/kcp-dev/api-syncagent/sdk@latest
+```
+
+and then in your code import the desired types:
+
+```go
+package main
+
+import apisyncagentv1alpha1 "github.com/kcp-dev/api-syncagent/sdk/apis/syncagent/v1alpha1"
+
+func createPublishedResource() *apisyncagentv1alpha1.PublishedResource {
+   pr := &apisyncagentv1alpha1.PublishedResource{}
+   pr.Name = "publish-crontabs"
+   pr.Namespace = "default"
+
+   return pr
+}
+```
+
+## SDK Design
+
+The SDK comes as a standalone Go module: `github.com/kcp-dev/api-syncagent/sdk`
+
+The module reduces the transitive dependencies that consumers have to worry about when they want to
+integrate the syncagent. To that end, the SDK is meant to provide the broadest possible
+compatibility: dependencies are on the *lowest* version that is usable by the syncagent. This drift
+between the syncagent's dependencies and those of the SDK is an intended feature of the SDK.
+
+The actual dependency versions used in the syncagent binaries are controlled exclusively via the
+root directory's `go.mod`. Specifically, the SDK is not meant to propagate security fixes to
+consumers and force them to upgrade when it might be inconvenient to them.
+
+## Development Guidelines
+
+* Do not update the `go` constraint in the `go.mod` file manually, let `go mod tidy` update it only
+  when necessary. The `go` constraint has no influence on what Go version the syncagent is actually
+  built with. It can, however, cause serious annoyances for downstream consumers.
+* Likewise, only bump dependencies to keep the SDK compatible with the main module.