docs: SDK documentation cleanup and examples fix (#753)

* feat(fn): add --help, --doc, and standalone file mode to AsMain

Extend fn.AsMain with functional options to support:
- --help: renders human-readable docs from embedded README markers
- --doc: outputs machine-readable JSON for catalog tooling
- Standalone file mode: accepts positional file args for local debugging

New fn.WithDocs(readme, meta) option registers embedded content.
Existing callers with no options are unaffected (backward-compatible).

Adds internal/docs package with:
- ParseMarkers: extracts mdtogo Short/Long/Examples sections
- ParseMetadata: parses metadata.yaml content
- RenderHelp/RenderDoc: formats output for --help and --doc

Includes property-based tests (rapid) and unit tests for all new code.

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* chore: apply go fix modernization

Mechanical changes from 'go fix ./...':
- interface{} → any (Go 1.18+ type alias)
- reflect.Ptr → reflect.Pointer (deprecated constant)
- strings.Index+slice → strings.Cut (Go 1.18+ idiom)

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* chore: gitignore rapid testdata failure files

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* fix: CI drift — use slices.Contains, fix file permissions

- Replace manual loops with slices.Contains for --help/--doc checks
  (matches what 'go fix' produces)
- Change test file permissions from 0644 to 0600 (gosec G306)

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* fix: use <- All existing tests continue tomdtogo--> as end marker (matches catalog READMEs)

The catalog functions use <- All existing tests continue tomdtogo--> (bare) as the section end marker,
not <- All existing tests continue tomdtogo:End-->. Updated the parser and all tests to match the
real-world README format.

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* fix: skip single-dash flags in file mode arg parsing

Go test runner passes -test.* flags via os.Args. The file mode arg
parser must skip all flag-like arguments (starting with -), not just
those starting with --.

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* docs: SDK documentation cleanup and examples fix

- Delete legacy docs/ directory (TypeScript API docs, Jekyll artifacts)
- Add docs/tutorial.md — end-to-end function development workflow
- Add docs/interfaces.md — Runner vs ResourceListProcessor guide
- Add docs/testing.md — golden test patterns with testhelpers
- Add docs/containerizing.md — Dockerfile patterns and local testing
- Add CONTRIBUTING.md aligned with kpt/catalog conventions
- Rewrite README.md with better flow and accurate descriptions
- Fix go/get-started/ to use //go:embed + fn.WithDocs
- Fix go/fn/examples/ go.mod
- Rename testdata/test1/ to testdata/noop-passthrough/
- Update gcr.io/kpt-fn/ references to ghcr.io/kptdev/krm-functions-catalog/
- Add replace directive comments in go.mod files
- Update .gitignore for compiled binary

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* docs: address PR review comments for text improvements

Apply text suggestions from mpgreaves review:
- Expand contractions (we'd, you'll, shouldn't, it's, you've, doesn't)
- Add missing periods to sentence fragments
- Improve sentence structure and clarity
- Use more formal phrasing in documentation

Assisted-by: Kiro:Auto [code-editing]
Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

---------

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

Author: efiacor

.gitignore

@@ -12,3 +12,6 @@ ts/create-kpt-functions/bin
 # 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 would 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 have been modified. If the CI script 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.