docs: restructure documentation with updated command references

Reorganize documentation into docs/ with commands/ and development/
subdirectories. Add CONTRIBUTING.md for contributor onboarding.

New structure:
- docs/commands/ — reference for all 5 commands (export, transform,
  apply, validate, transfer-pvc)
- docs/development/ — architecture, setup, testing, plugin development
- docs/multistage-pipeline.md — multi-stage Kustomize pipeline guide
- docs/plugins.md — plugin overview
- docs/resource-compatibility.md — resource type compatibility matrix
- docs/installation.md — installation and prerequisites

Content updated to reflect current codebase:
- crane apply uses embedded kustomize (no kubectl dependency)
- crane apply supports --skip-cluster-scoped and --kustomize-args flags
- crane validate supports offline mode via --api-resources
- crane export documents CRD collection and _cluster/ subdirectory

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

Author: Ilanit Stein

CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to Crane
+
+Thank you for your interest in contributing to Crane! This guide will help you get started.
+
+## Quick Start
+
+1. Fork and clone the repository:
+   ```bash
+   git clone https://github.com/<your-username>/crane.git
+   cd crane
+   ```
+
+2. Build the binary:
+   ```bash
+   go build -o crane main.go
+   ```
+
+3. Run tests:
+   ```bash
+   go test ./...
+   ```
+
+4. Submit a pull request
+
+## Prerequisites
+
+- **Go** 1.25+ (see `go.mod` for exact version)
+- **kubectl** (for deploying output to clusters and for `crane validate` with live cluster mode)
+- **Docker** (optional, for container-based testing)
+- Access to a Kubernetes cluster (for E2E testing)
+
+## Development Setup
+
+For detailed guides on architecture, testing, and advanced development workflows, see the [Development Documentation](docs/development/README.md).
+
+## Code Standards
+
+### Go Conventions
+
+- Follow standard Go idioms and [Effective Go](https://go.dev/doc/effective_go) practices
+- Use `gofmt` for formatting
+- Prefer explicit error messages with context — include the actual type received, the API resource being processed, and enough context to debug without re-running
+
+### Error Handling
+
+Error messages must be actionable:
+
+```go
+// Good — shows actual object type
+fmt.Errorf("expected *unstructured.Unstructured but got %T", object)
+
+// Bad — shows nil pointer
+fmt.Errorf("expected *unstructured.Unstructured but got %T", u)
+```
+
+### Working with Kubernetes API Objects
+
+- Use `*unstructured.Unstructured` for dynamic resources
+- Always check type assertions and provide informative error messages
+- Include the actual resource type and API resource name in errors
+
+## Commit Messages
+
+Use conventional commits format:
+
+- `fix:` for bug fixes
+- `feat:` for new features
+- `refactor:` for code restructuring
+- `test:` for test additions
+- `docs:` for documentation
+
+Include issue references where applicable: `fix: improve error messages (#197)`
+
+## Pull Request Guidelines
+
+**Title:** Clear and concise (under 70 characters)
+
+**Body must include:**
+- **Summary** — what changed and why
+- **Impact** — severity, affected components
+- **Test plan** — how to verify
+
+**Before submitting:**
+
+- [ ] Code compiles: `go build ./...`
+- [ ] Tests pass: `go test ./...`
+- [ ] Error messages are informative
+- [ ] No unnecessary refactoring in the same PR
+- [ ] Backward compatible (or documented breaking change)
+
+## Testing
+
+- All new features require tests
+- Bug fixes should include regression tests when possible
+- Use table-driven tests for multiple scenarios
+- Test files: `*_test.go` in the same package
+- E2E tests: `e2e-tests/`
+
+See [Testing Guide](docs/development/testing.md) for detailed testing documentation.
+
+## Reporting Issues
+
+- Check existing issues before filing a new one
+- Include reproduction steps, expected behavior, and actual behavior
+- Include Crane version, Go version, and Kubernetes version
+
+## Code of Conduct
+
+Be respectful and constructive. We follow the [Konveyor community guidelines](https://www.konveyor.io/).

README.md

@@ -99,7 +99,7 @@ How does it work? Crane works by:
     * `$ cat transform/10_KubernetesPlugin/resources/secret.yaml` - Contains the original exported Secret with all metadata
 
 5. `$ crane apply`
-  * Runs `kubectl kustomize` on the transform stage to apply patches
+  * Runs embedded kustomize on the transform stage to apply patches
   * Outputs clean, declarative YAML to `output/output.yaml`
   * Example:
     * `$ cat output/output.yaml`
@@ -117,6 +117,14 @@ How does it work? Crane works by:
 6. The content in `output/output.yaml` is now ready to be deployed to the target cluster or checked into Git for GitOps workflows:
     * `$ kubectl apply -f output/output.yaml`
 
+## Documentation
+
+For comprehensive documentation, see the [docs/](docs/README.md) directory:
+
+- [Installation](docs/installation.md)
+- [Command Reference](docs/README.md#command-reference) — export, transform, apply, validate, transfer-pvc
+- [Contributing](CONTRIBUTING.md) | [Development Guide](docs/development/README.md)
+
 ## Further Examples
 
 Please see [konveyor/crane-runner/main/examples](https://github.com/konveyor/crane-runner/tree/main/examples#readme) for further scenarios to explore what can be done with Crane + Tekton for migrating applications. 

docs/README.md

@@ -0,0 +1,30 @@
+# Crane Documentation
+
+Welcome to the Crane documentation. Crane is a Kubernetes migration tool that helps migrate workloads between clusters using a non-destructive pipeline: **export → transform → apply → validate**.
+
+## Getting Started
+
+- [Installation](./installation.md) — Prerequisites, building, and verifying the Crane binary
+
+## Command Reference
+
+- [`crane export`](./commands/export.md) — Export namespace resources from a source cluster
+- [`crane transform`](./commands/transform.md) — Transform exported resources using plugins and Kustomize
+- [`crane apply`](./commands/apply.md) — Apply transformations and produce final manifests
+- [`crane validate`](./commands/validate.md) — Validate final manifests against a target cluster
+- [`crane transfer-pvc`](./commands/transfer-pvc.md) — Transfer PVC data between clusters via rsync
+
+## Concepts
+
+- [Multi-Stage Pipeline](./multistage-pipeline.md) — How Crane's multi-stage Kustomize transform pipeline works
+- [Plugins](./plugins.md) — Built-in and custom plugin overview
+
+## Reference
+
+- [Pre-Apply Validation Guide](./pre-apply-validation-guide.md) — Checklist for validating manifests before applying
+- [Resource Compatibility](./resource-compatibility.md) — Supported resource types and migration boundaries
+
+## Development
+
+- [Development Guide](./development/README.md) — Architecture, setup, testing, and plugin development
+- [Contributing](../CONTRIBUTING.md) — How to contribute to Crane

docs/commands/apply.md

@@ -0,0 +1,106 @@
+# crane apply
+
+Apply transformations to exported resources and produce final manifests.
+
+## Synopsis
+
+```bash
+crane apply [flags]
+```
+
+## Description
+
+`crane apply` runs embedded kustomize on each transform stage to apply patches, producing clean, declarative YAML ready for deployment to a target cluster. By default, all stages are applied sequentially to maintain consistency across the pipeline. The output includes both a single multi-document YAML file and individual resource files organized by namespace.
+
+Kustomize is embedded directly in the Crane binary (via the krusty API), so no external `kubectl` dependency is needed.
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--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 |
+
+## Output Structure
+
+```text
+output/
+├── output.yaml                      # All resources in a single multi-document YAML
+└── resources/                       # Individual resource files
+    ├── <namespace>/
+    │   ├── Deployment_apps_v1_<ns>_<name>.yaml
+    │   ├── Service__v1_<ns>_<name>.yaml
+    │   └── ConfigMap__v1_<ns>_<name>.yaml
+    └── _cluster/                    # Cluster-scoped resources (when not skipped)
+        ├── ClusterRoleBinding_rbac.authorization.k8s.io_v1_clusterscoped_<name>.yaml
+        └── ClusterRole_rbac.authorization.k8s.io_v1_clusterscoped_<name>.yaml
+```
+
+- **`output.yaml`** — Ready for `kubectl apply -f`
+- **`resources/<namespace>/`** — Individual files for selective review or application
+- **`resources/_cluster/`** — Cluster-scoped resources (omitted when `--skip-cluster-scoped` is set)
+
+## Examples
+
+### Apply all stages (default)
+
+```bash
+crane apply
+```
+
+### Apply with custom directories
+
+```bash
+crane apply --transform-dir ./migration/transform --output-dir ./migration/output
+```
+
+### Apply a specific stage only
+
+```bash
+crane apply --stage 10_KubernetesPlugin
+```
+
+### Skip cluster-scoped resources
+
+```bash
+crane apply --skip-cluster-scoped
+```
+
+### Pass additional kustomize arguments
+
+```bash
+crane apply --kustomize-args "--enable-helm --helm-command=helm3"
+```
+
+### Deploy to target cluster
+
+```bash
+crane apply
+kubectl apply -f output/output.yaml
+```
+
+## Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `kustomization.yaml validation failed` | Invalid Kustomize syntax or missing resource files | Run `crane apply --stage <stage>` to isolate the failing stage |
+| `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 |
+
+## Next Steps
+
+After applying, validate the manifests against your target cluster:
+
+```bash
+crane validate --input-dir output --context target-cluster
+```
+
+See [crane validate](./validate.md) for details. Or deploy directly:
+
+```bash
+kubectl apply -f output/output.yaml
+```

docs/commands/export.md

@@ -0,0 +1,113 @@
+# crane export
+
+Export namespace resources from a source Kubernetes cluster to disk.
+
+## Synopsis
+
+```bash
+crane export [flags]
+```
+
+## Description
+
+`crane export` discovers all API types in a Kubernetes cluster, lists objects in the specified namespace (plus related cluster-scoped RBAC resources), and writes manifests to an export directory. This is the first step in the Crane migration pipeline.
+
+Exported resources are written as individual YAML files under `export/resources/<namespace>/`. Cluster-scoped resources related to the namespace (ClusterRoleBindings, ClusterRoles, SCCs) are written to `export/resources/<namespace>/_cluster/`. Any errors encountered during listing are recorded in `export/failures/<namespace>/`.
+
+### CRD Collection
+
+When custom resources are found in the namespace, Crane automatically collects their corresponding CustomResourceDefinitions. Operator-managed CRDs (identified via owner references) are skipped, since they should be installed by the operator on the target cluster rather than migrated directly. If the migration user lacks permission to read CRDs, Crane logs a warning and continues — the assumption is that the CRDs already exist on the target.
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--export-dir` | `-e` | `export` | The path where files are exported |
+| `--label-selector` | `-l` | | Restrict export to resources matching a label selector |
+| `--namespace` | `-n` | _(context default)_ | Namespace to export |
+| `--crd-skip-group` | | | API groups to skip for CRD export (repeatable) |
+| `--crd-include-group` | | | API groups to force-include for CRD export (repeatable) |
+| `--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 |
+
+Standard kubeconfig flags (`--kubeconfig`, `--context`, `--cluster`, `--as`, `--as-group`, etc.) are also available.
+
+## Output Structure
+
+```text
+export/
+├── resources/
+│   └── <namespace>/
+│       ├── Deployment_apps_v1_<ns>_<name>.yaml
+│       ├── Service__v1_<ns>_<name>.yaml
+│       ├── ConfigMap__v1_<ns>_<name>.yaml
+│       └── _cluster/
+│           ├── ClusterRoleBinding_rbac.authorization.k8s.io_v1_clusterscoped_<name>.yaml
+│           ├── ClusterRole_rbac.authorization.k8s.io_v1_clusterscoped_<name>.yaml
+│           └── CustomResourceDefinition_apiextensions.k8s.io_v1_clusterscoped_<name>.yaml
+└── failures/
+    └── <namespace>/
+        └── <error-files>
+```
+
+Resource filenames follow the format: `Kind_group_version_namespace_name.yaml`
+
+## Examples
+
+### Basic namespace export
+
+```bash
+crane export -n my-app
+```
+
+### Export with label selector
+
+```bash
+crane export -n my-app --label-selector "app=frontend"
+```
+
+### Export with custom directory
+
+```bash
+crane export -n my-app --export-dir ./migration/export
+```
+
+### Export with impersonation
+
+```bash
+crane export -n my-app --as system:serviceaccount:my-app:deployer
+```
+
+### Export with extra impersonation info
+
+```bash
+crane export -n my-app \
+  --as user@example.com \
+  --as-extras "scope=read,write;project=my-project"
+```
+
+### Export skipping specific CRD groups
+
+```bash
+crane export -n my-app --crd-skip-group monitoring.coreos.com
+```
+
+## Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `namespace must be set` | No namespace specified and none in kubeconfig context | Use `-n <namespace>` |
+| `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 |
+
+## Next Steps
+
+After exporting, transform the resources:
+
+```bash
+crane transform --export-dir export
+```
+
+See [crane transform](./transform.md) for details.