docs: update documentation for latest CLI changes and review feedback

Update all doc files to reflect 35 commits merged to main since the
original PR: --stage flag replaced with positional arguments, --overwrite
added to export/apply/validate, transform default behavior changed to
create stages for all plugins, --skip-plugins and --instructions-file
flags added, --api-resources mutual exclusion expanded, and
--plugin-priorities/--stage-name/--plugin-name flags removed.

Address reviewer feedback: use verb-first commit/PR titles instead of
conventional commit prefixes (aufi), add community plugin maintenance
note (aufi), fix conditional Required status for transfer-pvc nginx
flags (CodeRabbit), add defensive JSONPatch parent-object checks in
plugin examples (CodeRabbit), add nil check for GetAnnotations
(CodeRabbit), and resolve apply stage-specific flag contradiction
(CodeRabbit).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Ilanit Stein

CONTRIBUTING.md

@@ -59,17 +59,17 @@ fmt.Errorf("expected *unstructured.Unstructured but got %T", u)
 - Always check type assertions and provide informative error messages
 - Include the actual resource type and API resource name in errors
 
-## Commit Messages
+## Commit and PR Title Conventions
 
-Use conventional commits format:
+Use verb-first titles that describe what the change does:
 
-- `fix:` for bug fixes
-- `feat:` for new features
-- `refactor:` for code restructuring
-- `test:` for test additions
-- `docs:` for documentation
+- `Fix` for bug fixes (e.g., `Fix transform error on empty namespace`)
+- `Add` for new features (e.g., `Add crane validate command`)
+- `Update` for enhancements (e.g., `Update crane-lib with resources whiteout`)
+- `Refactor` for code restructuring
+- `Remove` for removals
 
-Include issue references where applicable: `fix: improve error messages (#197)`
+Include issue references where applicable: `Fix transform error on empty namespace (#197)`
 
 ## Pull Request Guidelines
 

docs/commands/apply.md

@@ -5,7 +5,7 @@ Apply transformations to exported resources and produce final manifests.
 ## Synopsis
 
 ```bash
-crane apply [flags]
+crane apply [stage...] [flags]
 ```
 
 ## Description
@@ -21,9 +21,11 @@ Kustomize is embedded directly in the Crane binary (via the krusty API), so no e
 | `--export-dir` | `-e` | `export` | The path where exported resources are saved (kept for consistency; not used by apply) |
 | `--transform-dir` | `-t` | `transform` | The path where transform stage directories are located |
 | `--output-dir` | `-o` | `output` | The path where final manifests are written |
-| `--stage` | | | Apply a specific stage only (e.g., `10_KubernetesPlugin`). If not specified, all stages are applied |
 | `--kustomize-args` | | | Additional arguments for kustomize (e.g., `--enable-helm --helm-command=helm3`) |
 | `--skip-cluster-scoped` | | `false` | Exclude cluster-scoped resources (ClusterRole, ClusterRoleBinding, CRD, etc.) from output. Useful for non-admin migration scenarios |
+| `--overwrite` | | `false` | Overwrite the output directory if it already exists |
+
+Stages are specified as positional arguments (e.g., `crane apply 10_KubernetesPlugin`). Stages can be specified by directory name or plugin name. If no stages are specified, all discovered stages are applied sequentially.
 
 ## Output Structure
 
@@ -61,7 +63,7 @@ crane apply --transform-dir ./migration/transform --output-dir ./migration/outpu
 ### Apply a specific stage only
 
 ```bash
-crane apply --stage 10_KubernetesPlugin
+crane apply 10_KubernetesPlugin
 ```
 
 ### Skip cluster-scoped resources
@@ -87,7 +89,8 @@ kubectl apply -f output/output.yaml
 
 | Error | Cause | Solution |
 |-------|-------|----------|
-| `kustomization.yaml validation failed` | Invalid Kustomize syntax or missing resource files | Run `crane apply --stage <stage>` to isolate the failing stage |
+| `kustomization.yaml validation failed` | Invalid Kustomize syntax or missing resource files | Run `crane apply <stage>` to isolate the failing stage |
+| `output directory "X" already exists` | Output directory from a previous run | Use `--overwrite` to replace it |
 | `invalid stage name` | Stage name doesn't follow `<number>_<name>` format | Use a valid stage name like `10_KubernetesPlugin` |
 | `invalid kustomize-args` | Unsupported or malformed kustomize arguments | Check supported kustomize flags |
 

docs/commands/export.md

@@ -30,9 +30,12 @@ When custom resources are found in the namespace, Crane automatically collects t
 | `--as-extras` | | | Extra impersonation info (format: `key=val1,val2;key2=val3`) |
 | `--qps` | `-q` | `100` | Query-per-second rate for API requests |
 | `--burst` | `-b` | `1000` | API burst rate |
+| `--overwrite` | | `false` | Overwrite the export directory if it already exists |
 
 Standard kubeconfig flags (`--kubeconfig`, `--context`, `--cluster`, `--as`, `--as-group`, etc.) are also available.
 
+> **Note:** `--context` is mutually exclusive with `--cluster`, `--server`, `--user`, and `--token`.
+
 ## Output Structure
 
 ```text
@@ -101,6 +104,8 @@ crane export -n my-app --crd-skip-group monitoring.coreos.com
 | `namespaces "X" not found` | Namespace does not exist | Verify namespace name |
 | `cannot verify namespace exists` | Insufficient RBAC (warning only) | Export proceeds; verify namespace exists manually |
 | `extras requires specifying a user or group` | `--as-extras` used without `--as` | Add `--as` or `--as-group` flag |
+| `export directory "X" already exists` | Export directory from a previous run | Use `--overwrite` to replace it |
+| Non-zero exit with aggregated error | All namespace list calls returned Forbidden | Ensure service account has list permissions on at least one namespace |
 
 ## Next Steps
 

docs/commands/transfer-pvc.md

@@ -33,8 +33,8 @@ The above command transfers PVC (along with PV data) named `<pvc_name>` in the n
 | `--destination-image` | string | No | Custom image to use for destination rsync Pod |
 | `--source-image` | string | No | Custom image to use for source rsync Pod |
 | `--endpoint` | string | No | Kind of endpoint to create in destination cluster (see [Endpoint Options](#endpoint-options)) |
-| `--ingress-class` | string | No | Ingress class when endpoint is nginx-ingress |
-| `--subdomain` | string | No | Custom subdomain to use for the endpoint |
+| `--ingress-class` | string | When endpoint is nginx-ingress | Ingress class when endpoint is nginx-ingress |
+| `--subdomain` | string | When endpoint is nginx-ingress | Custom subdomain to use for the endpoint |
 | `--output` | string | No | Output transfer stats in the specified file |
 | `--verify` | bool | No | Verify transferred files using checksums |
 

docs/commands/transform.md

@@ -58,7 +58,7 @@ You can edit resources in the `resources/` directory:
 vi transform/10_KubernetesPlugin/resources/Deployment_apps_v1_default_wordpress.yaml
 
 # Preview changes
-crane apply --stage 10_KubernetesPlugin
+crane apply 10_KubernetesPlugin
 
 # Apply changes
 kubectl apply -f output/output.yaml
@@ -128,21 +128,32 @@ transform/.work/
 
 ```bash
 # Default: discover and run all existing stages
-# If no stages exist, creates default 10_KubernetesPlugin stage
+# If no stages exist, creates stages for all available plugins
 crane transform
 
-# Run specific stage only (creates it if doesn't exist)
-crane transform --stage 10_KubernetesPlugin
+# Run specific stages only (creates them if they don't exist)
+crane transform 10_KubernetesPlugin
+
+# Run multiple specific stages
+crane transform 10_KubernetesPlugin 20_OpenshiftPlugin
 
 # Create a new plugin-based stage automatically
 # Stage name ending with "Plugin" will use that plugin
-crane transform --stage 35_OpenshiftPlugin
+crane transform 35_OpenshiftPlugin
 
 # Create a new pass-through stage for manual editing
 # Stage name NOT ending with "Plugin" creates empty pass-through
-crane transform --stage 40_CustomManualEdits
+crane transform 40_CustomManualEdits
+
+# Skip specific plugins when running all stages
+crane transform --skip-plugins OpenshiftPlugin
+
+# Use a declarative instructions file (mutually exclusive with positional stage args)
+crane transform --instructions-file instructions.yaml
 ```
 
+Shell autocompletion is available for plugin and stage names.
+
 ### Applying Transforms
 
 ```bash
@@ -176,7 +187,9 @@ output/
 
 ## Automatic Stage Creation
 
-Crane automatically creates new stages when you reference them with `--stage`. The stage name determines whether a plugin will be used or if it's a pass-through stage for manual editing.
+When no stages exist in the transform directory, `crane transform` automatically creates stages for **all available plugins** (not just KubernetesPlugin). Plugins are sorted alphabetically and assigned priorities starting at 10, incrementing by 5. Use `--skip-plugins` to exclude specific plugins from this default behavior.
+
+You can also create new stages by specifying them as positional arguments. The stage name determines whether a plugin will be used or if it's a pass-through stage for manual editing.
 
 ### Stage Naming Convention
 
@@ -198,7 +211,7 @@ Stage names ending with `Plugin` **must** have a corresponding plugin installed.
 
 ```bash
 # Creates a stage using OpenshiftPlugin
-crane transform --stage 20_OpenshiftPlugin
+crane transform 20_OpenshiftPlugin
 
 # Output:
 # - resources/ (from previous stage or export)
@@ -209,7 +222,7 @@ crane transform --stage 20_OpenshiftPlugin
 **If the plugin doesn't exist, you'll get an error:**
 
 ```bash
-crane transform --stage 20_NonexistentPlugin
+crane transform 20_NonexistentPlugin
 # Error: stage 20_NonexistentPlugin requires plugin 'NonexistentPlugin' 
 #        but it was not found (available plugins: KubernetesPlugin, NamespaceCleanup)
 ```
@@ -220,7 +233,7 @@ Stage names **not** ending with `Plugin` create pass-through stages where resour
 
 ```bash
 # Creates a pass-through stage for manual editing
-crane transform --stage 30_CustomEdits
+crane transform 30_CustomEdits
 
 # Output:
 # - resources/ (copied unchanged from previous stage)
@@ -334,7 +347,7 @@ kubectl kustomize transform/10_KubernetesPlugin/
 
 ```bash
 # Create a custom stage for manual edits
-crane transform --stage 40_CustomEdits
+crane transform 40_CustomEdits
 
 # Edit resources
 vi transform/40_CustomEdits/resources/Deployment_apps_v1_default_wordpress.yaml
@@ -361,10 +374,10 @@ crane transform
 crane transform --force
 
 # Run specific plugin stage (regenerates automatically)
-crane transform --stage 10_KubernetesPlugin
+crane transform 10_KubernetesPlugin
 
 # Run specific custom stage (requires --force if directory not empty)
-crane transform --stage 40_CustomEdits --force
+crane transform 40_CustomEdits --force
 ```
 
 ### 4. Working with Multiple Stages
@@ -374,11 +387,11 @@ crane transform --stage 40_CustomEdits --force
 crane transform
 
 # Automatically add more plugin stages
-crane transform --stage 20_OpenshiftPlugin
-crane transform --stage 30_ImagestreamPlugin
+crane transform 20_OpenshiftPlugin
+crane transform 30_ImagestreamPlugin
 
 # Add a manual editing stage
-crane transform --stage 40_CustomEdits
+crane transform 40_CustomEdits
 
 # Edit the manual stage (example: edit a specific deployment)
 vi transform/40_CustomEdits/resources/Deployment_apps_v1_default_wordpress.yaml
@@ -402,11 +415,11 @@ crane transform
 # Creates: 10_KubernetesPlugin/
 
 # 3. Add OpenShift-specific transformations
-crane transform --stage 20_OpenshiftPlugin
+crane transform 20_OpenshiftPlugin
 # Creates: 20_OpenshiftPlugin/ using OpenshiftPlugin
 
 # 4. Add a manual customization stage
-crane transform --stage 50_CustomLabels
+crane transform 50_CustomLabels
 # Creates: 50_CustomLabels/ as pass-through (resources copied from previous stage)
 
 # 5. Manually add custom labels
@@ -483,7 +496,7 @@ crane transform --force
 git diff transform/
 
 # Option 3: Only regenerate plugin stages (they auto-regenerate)
-crane transform --stage 10_KubernetesPlugin
+crane transform 10_KubernetesPlugin
 
 # Note: Plugin stages (ending with "Plugin") regenerate automatically without --force
 # Custom stages (not ending with "Plugin") require --force to protect manual edits
@@ -496,7 +509,7 @@ crane transform --stage 10_KubernetesPlugin
 **Solution**:
 ```bash
 # Validate by applying a single stage
-crane apply --stage 10_KubernetesPlugin
+crane apply 10_KubernetesPlugin
 
 # Check for missing files
 ls -la transform/10_KubernetesPlugin/resources/

docs/commands/validate.md

@@ -18,7 +18,7 @@ Incompatible resources are written to a `failures/` directory under the validate
 
 ### Offline Validation
 
-Use `--api-resources` to validate offline against a captured API surface JSON file (produced by `scripts/capture-api-surface.sh`) when the target cluster is not directly reachable. This is mutually exclusive with `--context`/`--kubeconfig`.
+Use `--api-resources` to validate offline against a captured API surface JSON file (produced by `scripts/capture-api-surface.sh`) when the target cluster is not directly reachable. This is mutually exclusive with `--context`, `--kubeconfig`, `--server`, `--token`, `--cluster`, and `--user`.
 
 ## Flags
 
@@ -27,7 +27,8 @@ Use `--api-resources` to validate offline against a captured API surface JSON fi
 | `--input-dir` | `-i` | `output` | Path to the apply output directory containing final manifests |
 | `--validate-dir` | | `validate` | Path where validation results and failures are saved |
 | `--output` | `-o` | `json` | Report file format: `json` or `yaml` |
-| `--api-resources` | | | Path to API surface JSON file for offline validation (mutually exclusive with `--context`/`--kubeconfig`) |
+| `--api-resources` | | | Path to API surface JSON file for offline validation (mutually exclusive with `--context`/`--kubeconfig`/`--server`/`--token`/`--cluster`/`--user`) |
+| `--overwrite` | | `false` | Overwrite the validate directory if it already exists |
 
 Standard kubeconfig flags (`--kubeconfig`, `--context`, `--cluster`, etc.) are also available to specify the target cluster for live validation.
 
@@ -94,7 +95,8 @@ crane validate --context target-cluster
 |-------|-------|----------|
 | `input-dir "X" is not a directory` | Path doesn't exist or isn't a directory | Run `crane apply` first to generate output |
 | `loading kubeconfig` | Cannot connect to target cluster | Check kubeconfig and `--context` flag, or use `--api-resources` for offline mode |
-| `--api-resources and --context are mutually exclusive` | Both offline and live flags specified | Use one mode or the other |
+| `--api-resources and --context are mutually exclusive` | Both offline and live flags specified | Use one mode or the other. `--api-resources` is also mutually exclusive with `--kubeconfig`, `--server`, `--token`, `--cluster`, and `--user` |
+| `validate directory "X" already exists` | Validate directory from a previous run | Use `--overwrite` to replace it |
 | Validation failures | GVKs not available on target cluster | Install required CRDs/operators on target, or transform manifests to use supported API versions |
 
 ## Next Steps

docs/development/plugin-development.md

@@ -81,7 +81,12 @@ func main() {
 
     var patches []PatchOp
 
-    // Example: add a migration label
+    // Example: add a migration label (ensure parent object exists first)
+    patches = append(patches, PatchOp{
+        Op:    "add",
+        Path:  "/metadata/labels",
+        Value: map[string]interface{}{},
+    })
     patches = append(patches, PatchOp{
         Op:    "add",
         Path:  "/metadata/labels/migrated-by",
@@ -90,11 +95,13 @@ func main() {
 
     // Example: remove a specific annotation
     annotations := resource.GetAnnotations()
-    if _, ok := annotations["source-cluster-only"]; ok {
-        patches = append(patches, PatchOp{
-            Op:   "remove",
-            Path: "/metadata/annotations/source-cluster-only",
-        })
+    if annotations != nil {
+        if _, ok := annotations["source-cluster-only"]; ok {
+            patches = append(patches, PatchOp{
+                Op:   "remove",
+                Path: "/metadata/annotations/source-cluster-only",
+            })
+        }
     }
 
     if err := json.NewEncoder(os.Stdout).Encode(patches); err != nil {
@@ -115,9 +122,11 @@ go build -o ~/.local/share/crane/plugins/MyCustomPlugin
 ```bash
 #!/bin/bash
 # Simple plugin that adds a label to all resources
+# Note: ensure /metadata/labels exists before adding child keys
 
 cat <<EOF
 [
+  {"op": "add", "path": "/metadata/labels", "value": {}},
   {"op": "add", "path": "/metadata/labels/environment", "value": "production"}
 ]
 EOF
@@ -147,7 +156,7 @@ Stage naming convention:
 cat sample-deployment.json | ./MyCustomPlugin
 
 # Test in a full pipeline
-crane transform --stage 20_MyCustomPlugin
+crane transform 20_MyCustomPlugin
 crane apply
 ```
 
@@ -181,7 +190,7 @@ Plugins are executed in stage order (by the numeric prefix). Lower numbers run f
 ## Best Practices
 
 1. **Idempotent**: Running the plugin multiple times should produce the same result
-2. **Defensive**: Check if fields exist before removing them
+2. **Defensive**: Check if fields and parent objects exist before modifying them
 3. **Focused**: Each plugin should handle one concern
 4. **Documented**: Include usage instructions and examples
 5. **Tested**: Cover edge cases (missing fields, different resource types)