docs: clarify golden-test, interface, and file-mode behavior

Add behavioral details verified against the SDK source:
- testing: Kptfile counted as input, non-YAML files ignored, inputs read in
  sorted order, and WRITE_GOLDEN_OUTPUT intentionally fails the writing run
- interfaces: note the ConfigMap .data functionConfig path and that the
  Runner no-add/remove rule is a convention, not a compile-time restriction
- containerizing: note file mode uses an empty functionConfig

Refs #4725

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

Author: efiacor

documentation/content/en/guides/krm-functions/containerizing.md

@@ -92,6 +92,10 @@ docker run --rm -i ghcr.io/kptdev/krm-functions-catalog/my-function:v0.1 < input
 docker run --rm -v $(pwd):/data ghcr.io/kptdev/krm-functions-catalog/my-function:v0.1 /data/deployment.yaml
 ```
 
+Note: file mode assembles the given files into a ResourceList with an **empty
+functionConfig**. Functions that require configuration should be run via STDIN
+(or a `kpt` pipeline) so the functionConfig is provided.
+
 ### Help and doc flags
 
 ```bash

documentation/content/en/guides/krm-functions/interfaces.md

@@ -28,8 +28,14 @@ type Runner interface {
 ```
 
 Characteristics:
-- The SDK automatically parses `functionConfig` into your struct's exported fields (via JSON tags).
-- You can **modify** existing items, but you cannot add or remove items from the slice.
+- The SDK automatically parses `functionConfig` into your struct's exported fields.
+  A typed functionConfig (its `kind` matching your struct name) is unmarshaled via
+  JSON tags; alternatively, a `ConfigMap` functionConfig has its `.data` map assigned
+  to a `map[string]string` field on your struct.
+- You can **modify** existing items, but adding or removing items is not supported.
+  This is a convention, not a compile-time restriction: the SDK does not read back
+  items appended inside `Run`, so adds and removes are effectively dropped. Use
+  `fn.ResourceListProcessor` when you need to add or remove items.
 - Return `true` for success, `false` for failure.
 - Use `results` to report structured info/warning/error messages.
 

documentation/content/en/guides/krm-functions/testing.md

@@ -34,8 +34,11 @@ Conventions:
 - Files prefixed with `_` are special — they are not included in the input items.
 - `_fnconfig.yaml` contains the functionConfig passed to your function.
 - `_expected.yaml` contains the expected ResourceList output.
-- All other `.yaml` files in the directory are parsed as input resources.
+- All other `.yaml`/`.yml` files (and a `Kptfile`, if present) are parsed as input
+  resources. Files with any other extension are ignored.
 - You can have multiple input files (e.g., `deployments.yaml`, `services.yaml`).
+  Input files are read in sorted (alphabetical) order, so the assembled item
+  ordering is deterministic.
 
 ### Writing a Golden Test
 
@@ -51,7 +54,7 @@ import (
 )
 
 func TestFunction(t *testing.T) {
-    runner := fn.WithContext(context.TODO(), &YourFunction{})
+    runner := fn.WithContext(context.TODO(), &SetLabels{})
     testhelpers.RunGoldenTests(t, "testdata", runner)
 }
 ```
@@ -136,8 +139,12 @@ When your function's output changes intentionally, regenerate the expected files
 WRITE_GOLDEN_OUTPUT=1 go test ./...
 ```
 
-This overwrites all `_expected.yaml` files with the actual output. Review the
-diffs in version control before committing.
+This overwrites any `_expected.yaml` that differs from the actual output. Any
+non-empty value enables write mode (`WRITE_GOLDEN_OUTPUT=1`, `=true`, etc.).
+Note that the run which writes a golden file is reported as a **test failure**
+(`wrote output to ...`) — this is intentional, so a rewrite never silently
+passes in CI. Re-run the tests without the env var to confirm they pass, and
+review the diffs in version control before committing.
 
 **Caution:** `WRITE_GOLDEN_OUTPUT` accepts whatever the function currently
 produces as "correct." If the function has a bug, you have just blessed buggy