docs: SDK documentation cleanup and examples fix

.gitignore

@@ -9,3 +9,9 @@ ts/create-kpt-functions/bin
 *.swo
 *.swp
 
+# rapid property-based testing failure reproductions
+**/testdata/rapid/
+
+# compiled binaries
+go/get-started/get-started
+

CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to krm-functions-sdk
+
+We'd love to accept your contributions to this project. There are just a few
+small guidelines you need to follow.
+
+## Developer Certificate of Origin (DCO)
+
+Contributors to this project should state that they agree with the terms published
+at https://developercertificate.org/ for their contribution. To do this when
+creating a commit with the Git CLI, a sign-off can be added with
+[the -s option](https://git-scm.com/docs/git-commit#git-commit--s). The sign-off
+is stored as part of the commit message itself.
+
+## Copyright notices
+
+All files should have the copyright notice.
+```
+// Copyright 2026 The kpt Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+```
+
+If the file has never been modified: use the creation year only
+
+* Example: `Copyright 2026 The kpt Authors`
+
+If the file has been modified: use a year range from creation to last modification
+
+* Example: `Copyright 2024-2026 The kpt Authors`
+
+## Building and Testing
+
+The SDK uses a Makefile-based workflow. From the repository root:
+
+```bash
+# Run all checks (fix, vet, fmt, test, lint)
+make go
+
+# Run only tests
+cd go && make test
+
+# Run only linting
+cd go && make lint
+
+# Tidy all go.mod files
+make tidy
+```
+
+The CI script (`hack/ci-validate-go.sh`) runs `make go` and then checks that no
+files were modified. If CI fails with "files are not to date", run `make go`
+locally and commit the changes.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult [GitHub Help] for more
+information on using pull requests.
+
+Process for code reviews. Before requesting human review, a PR must:
+
+* All tests passing
+* All linting passing
+* Meeting project code quality requirements, including passing all configured
+  static analysis and not reducing automated test coverage
+* The comments from the first run of automatically generated comments (AI
+  generated comments, bot generated comments, etc.) of the PR are addressed
+  (addressing further re-runs of AI are optional)
+* If it is not possible to resolve an automatic comment, please add a sub-comment
+  indicating why the automated comment cannot be resolved or ask for help in
+  resolving the comment
+* The PR description states whether AI was used to help create the PR; if so, it
+  lists the AI tools used and the areas where they were used
+
+## Declare any use of AI
+
+> In addition to the above, the use of AI in the creation of PRs is allowed, but
+> you must declare any use of AI and you must be able to explain the PR code
+> independently of any AI tools.
+
+Update the PR description to state whether you used AI to help you create this
+PR; if so, list the AI tools you have used and in what areas.
+
+For example:
+```text
+I have used AI in the creation of this PR.
+
+I have used the following AI tools:
+- GitHub Copilot to analyse the code
+- Kiro to generate the implementation and tests
+```
+
+### Attribute AI in the Git commit messages
+
+Following the [guidance of the Linux kernel](https://docs.kernel.org/process/coding-assistants.html#attribution)
+we recommend the attribution of AI tools in the commit messages using the following format:
+
+```text
+Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+```
+
+## Community Guidelines
+
+This project follows a [Code of Conduct].
+
+## Community Discussion Groups
+
+1. Join our [Slack channel](https://kubernetes.slack.com/channels/kpt)
+1. Join our [Discussions](https://github.com/kptdev/kpt/discussions)
+
+## Governance
+
+The governance of the kpt project is described in the
+[governance repo](https://github.com/kptdev/governance).
+
+[GitHub Help]: https://help.github.com/articles/about-pull-requests/
+[Code of Conduct]: code-of-conduct.md

README.md

@@ -1,43 +1,111 @@
 # KRM Functions SDK
+
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkptdev%2Fkrm-functions-sdk.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkptdev%2Fkrm-functions-sdk?ref=badge_shield)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10658/badge)](https://www.bestpractices.dev/projects/10658)
 
-An opinionated Go SDK for implementing KRM functions.
+An opinionated Go SDK for implementing [KRM functions](https://kpt.dev/book/05-developing-functions/).
 
-## Documentation
+## Quick Start
 
-[Documentation](https://kpt.dev/book/05-developing-functions/#developing-in-go)
+A KRM function is a program that reads Kubernetes resources from STDIN, transforms or validates them, and writes the result to STDOUT. The SDK handles the I/O — you write the logic.
 
-## Issues
+```go
+package main
+
+import (
+    "context"
+    _ "embed"
+    "os"
+
+    "github.com/kptdev/krm-functions-sdk/go/fn"
+)
+
+//go:embed README.md
+var readme []byte
+
+//go:embed metadata.yaml
+var metadata []byte
+
+type SetLabels struct {
+    Labels map[string]string `json:"labels,omitempty"`
+}
+
+func (r *SetLabels) Run(ctx *fn.Context, functionConfig *fn.KubeObject, items fn.KubeObjects, results *fn.Results) bool {
+    for _, obj := range items {
+        for k, v := range r.Labels {
+            obj.SetLabel(k, v)
+        }
+    }
+    return true
+}
+
+func main() {
+    runner := fn.WithContext(context.Background(), &SetLabels{})
+    if err := fn.AsMain(runner, fn.WithDocs(readme, metadata)); err != nil {
+        os.Exit(1)
+    }
+}
+```
+
+A starter template is available at [`go/get-started/`](go/get-started/main.go). For the full walkthrough, see the [Tutorial](docs/tutorial.md).
+
+## How It Works
 
-Please [Open Issues](https://github.com/kptdev/kpt/issues) for this repo at [kptdev/kpt](https://github.com/kptdev/kpt/).
+`fn.AsMain` is the single entrypoint. It handles:
 
-## Pull requests
+- **STDIN/STDOUT** (default) — reads a ResourceList, processes it, writes the result
+- **File mode** — pass file paths as positional args for local debugging
+- **`--help`** — prints human-readable docs from embedded README markers
+- **`--doc`** — outputs machine-readable JSON (consumed by `kpt fn doc` and catalog pipelines)
 
-Open pull requests [here](https://github.com/kptdev/krm-functions-sdk/pulls).
+Register embedded documentation with `fn.WithDocs`:
 
-## Discussions
+```go
+fn.AsMain(runner, fn.WithDocs(readme, metadata))
+```
 
-Discussions are [here](https://github.com/kptdev/kpt/discussions).
+The SDK provides two interfaces for implementing functions:
+
+| Interface | Use for | Can add/remove items? | Auto-parses config? |
+|---|---|---|---|
+| `fn.Runner` | Transformers, validators | No | Yes |
+| `fn.ResourceListProcessor` | Generators, complex functions | Yes | No |
+
+See [Interfaces](docs/interfaces.md) for details and code examples.
+
+## Documentation
+
+- [API Reference](https://pkg.go.dev/github.com/kptdev/krm-functions-sdk/go/fn) — Go API docs
+- [Tutorial](docs/tutorial.md) — end-to-end function development
+- [Interfaces](docs/interfaces.md) — Runner vs ResourceListProcessor
+- [Testing](docs/testing.md) — golden test patterns
+- [Containerizing](docs/containerizing.md) — building and running function images
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on DCO sign-off, copyright headers, and code review process.
+
+## Issues
+
+Please [open issues](https://github.com/kptdev/kpt/issues) at [kptdev/kpt](https://github.com/kptdev/kpt/).
 
 ## License
 
 Code is under the [Apache License 2.0](LICENSE), documentation is [CC BY 4.0](LICENSE-documentation).
 
-
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkptdev%2Fkrm-functions-sdk.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkptdev%2Fkrm-functions-sdk?ref=badge_large)
 
 ## Governance
 
-The governance of the kpt project and KRM Functiona Catalog are described in the
+The governance of the kpt project is described in the
 [governance repo](https://github.com/kptdev/governance).
 
 ## Code of Conduct
 
-The kpt project and the KRM Functions Catalog are following the
+The kpt project follows the
 [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
-More information and links about the CNCF Code of Conduct are [here](code-of-conduct.md).
+More information is [here](code-of-conduct.md).
 
 ## CNCF
 
-The kpt project including the KRM Functions Catalog is a [CNCF Sandbox](https://www.cncf.io/sandbox-projects/) project.
+The kpt project is a [CNCF Sandbox](https://www.cncf.io/sandbox-projects/) project.