📖 Add getting-started guide and sample CRs (#140)

## Summary

Adds user-facing documentation and sample manifests so new contributors
and testers can deploy the controller and configure agent workloads
without reverse-engineering the codebase.

### What's included

**Getting-started guide** (`docs/getting-started.md`):
- Prerequisites (K8s 1.33+, Agent Sandbox)
- Deploying the controller (`make deploy`)
- Creating Gateways with credentials for each provider
- Creating an Agent and triggering an AgentRun
- Workflow pointers, local dev, e2e testing, troubleshooting

**Sample CRs** (`config/samples/`):
- `gateway_vertex_ai.yaml` — GCP Vertex AI with Claude
- `gateway_openai.yaml` — OpenAI GPT-4o
- `gateway_anthropic.yaml` — Anthropic direct API
- `gateway_aws_bedrock.yaml` — AWS Bedrock
- `agent_example.yaml` — Java migration agent referencing a gateway and
skill
- `agentrun_example.yaml` — Triggers the migration agent

Sample CRs are self-contained reference examples with inline
comments explaining prerequisites (e.g. secret creation commands).
They are not added to the samples kustomization since they require
user-specific credentials.

**README update**: Added a "Getting started" section linking to the
new guide.

### Context

From team discussion: multiple people were blocked on testing because
there was no documentation on how to configure things after deploying
the controller. The `LLMProvider` CRD was renamed to `Gateway` and
some team members were still on the old version without realizing.

### ADR compatibility

Reviewed all open ADR PRs (#108, #106, #138) before writing. The
guide stays at the CRD-level user interface and does not describe
internal delivery mechanisms (params.json, skill loading, ACP
transport) that are in flux. Nothing here contradicts pending
decisions.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added sample configurations for Agents, AgentRuns, and AI gateways
across Anthropic, AWS Bedrock, OpenAI, and Vertex AI.
* Added a Java EE-to-Quarkus migration Agent example with repository and
branch parameters.
* **Documentation**
* Added a comprehensive getting-started guide covering setup,
deployment, provider configuration, workflows, testing, cleanup, and
troubleshooting.
  * Added a README link to the getting-started guide.
* **Bug Fixes**
* Updated the AWS Bedrock example to use the Claude Sonnet 4.5 model
identifier.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: David Zager <david.j.zager@gmail.com>
Signed-off-by: Dylan Murray <dymurray@redhat.com>
Co-authored-by: Dylan Murray <dymurray@redhat.com>

Author: djzager

README.md

@@ -42,6 +42,12 @@ CI pipeline) resolves application metadata before creating the CR.
 
 See `docs/adr/` for the full set of architecture decision records.
 
+## Getting started
+
+See [docs/getting-started.md](docs/getting-started.md) for a
+step-by-step guide to deploying the controller, configuring a Gateway
+with LLM credentials, and creating your first AgentRun.
+
 ## Project structure
 
 ```

config/samples/agent_example.yaml

@@ -0,0 +1,34 @@
+# Example Agent for Java EE to Quarkus migration.
+#
+# An Agent is a template — it declares what is available (image,
+# gateways, skills) but does not execute anything. Create an AgentRun
+# to trigger execution.
+#
+# Prerequisites:
+#   - A Gateway CR (e.g. gateway_vertex_ai.yaml)
+#   - SkillCard CRs (the default samples or your own)
+apiVersion: konveyor.io/v1alpha1
+kind: Agent
+metadata:
+  name: migration-agent
+spec:
+  # Container image carrying the agent runtime and toolchains.
+  image: quay.io/konveyor/agent-java:latest
+
+  # Standing instructions for how the agent operates.
+  prompt: |
+    You are a migration agent. Analyze the source repository and
+    migrate it from Java EE to Quarkus 3.
+
+  # Gateways available for runs. An AgentRun selects one.
+  gateways:
+    - ref: gcp-vertex-ai
+
+  # Skills available to the agent.
+  skillCards:
+    - ref: javaee-to-quarkus
+
+  # No params: the agent-java harness resolves the repository to migrate
+  # (and its git credentials) from Konveyor Hub by APP_ID, and reads the
+  # target branch from the TARGET_BRANCH env var — neither comes from run
+  # parameters. See docs/getting-started.md section 5.

config/samples/agentrun_example.yaml

@@ -0,0 +1,43 @@
+# Example AgentRun — triggers execution of an Agent.
+#
+# An AgentRun is immutable once created. To change values, delete
+# and recreate the AgentRun.
+#
+# Prerequisites:
+#   - The referenced Agent CR (e.g. agent_example.yaml)
+#   - The Gateway selected here must be in the Agent's gateway list
+#   - A Konveyor Hub with the application registered — the harness clones
+#     the repo and reads git credentials from Hub by APP_ID. See
+#     hack/install-konveyor.sh and docs/getting-started.md section 5.
+apiVersion: konveyor.io/v1alpha1
+kind: AgentRun
+metadata:
+  name: migration-run-001
+spec:
+  # Reference to the Agent to execute.
+  agentRef: migration-agent
+
+  # Select which gateway (provider/model) to use for this run.
+  # Must be one of the gateways declared on the Agent.
+  # Note: Agent uses `gateways: [{ref: name}]` (a list of refs)
+  # because it declares multiple available options. AgentRun uses a
+  # bare string because it selects exactly one.
+  gateway: gcp-vertex-ai
+
+  # The harness resolves the repository and git credentials from Konveyor
+  # Hub by APP_ID and reads the target branch from TARGET_BRANCH, so this
+  # run carries a Hub connection rather than source_url/target_branch
+  # params. Edit these to match your Hub and registered application.
+  env:
+    - name: HUB_BASE_URL
+      value: "http://tackle-hub.konveyor-tackle.svc:8080"
+    - name: APP_ID
+      value: "1"
+    - name: TARGET_BRANCH
+      value: "konveyor/migration"
+
+  # Task-specific instructions for this run. Composed with the
+  # Agent's prompt at execution time.
+  instructions: |
+    Focus on the EJB-to-CDI migration first. Run mvn compile after
+    each major change to catch errors early.

config/samples/gateway_anthropic.yaml

@@ -0,0 +1,19 @@
+# Gateway for Anthropic (direct API).
+#
+# Prerequisites — create a Secret with your real API key:
+#   kubectl create secret generic anthropic-credentials \
+#     --from-literal=api-key="<your-anthropic-api-key>"
+apiVersion: konveyor.io/v1alpha1
+kind: Gateway
+metadata:
+  name: anthropic
+spec:
+  provider: anthropic
+  endpoint: "https://api.anthropic.com"
+  credentialRef:
+    secretName: anthropic-credentials
+    key: api-key
+  model:
+    name: claude-sonnet-4-5-20250929
+    contextWindow: 200000
+    tier: premium

config/samples/gateway_aws_bedrock.yaml

@@ -0,0 +1,23 @@
+# Gateway for AWS Bedrock.
+#
+# Prerequisites — create a Secret with your real AWS credentials:
+#   kubectl create secret generic bedrock-credentials \
+#     --from-literal=AWS_ACCESS_KEY_ID="<your-access-key-id>" \
+#     --from-literal=AWS_SECRET_ACCESS_KEY="<your-secret-access-key>" \
+#     --from-literal=AWS_REGION="<your-region>"
+#
+# The credential Secret uses envFrom (no key field) because Bedrock
+# requires multiple AWS env vars.
+apiVersion: konveyor.io/v1alpha1
+kind: Gateway
+metadata:
+  name: aws-bedrock
+spec:
+  provider: aws-bedrock
+  endpoint: "https://bedrock-runtime.us-east-1.amazonaws.com"
+  credentialRef:
+    secretName: bedrock-credentials
+  model:
+    name: us.anthropic.claude-sonnet-4-5-20250929-v1:0
+    contextWindow: 200000
+    tier: premium

config/samples/gateway_openai.yaml

@@ -0,0 +1,19 @@
+# Gateway for OpenAI.
+#
+# Prerequisites — create a Secret with your real API key:
+#   kubectl create secret generic openai-credentials \
+#     --from-literal=api-key="<your-openai-api-key>"
+apiVersion: konveyor.io/v1alpha1
+kind: Gateway
+metadata:
+  name: openai
+spec:
+  provider: openai
+  endpoint: "https://api.openai.com"
+  credentialRef:
+    secretName: openai-credentials
+    key: api-key
+  model:
+    name: gpt-4o
+    contextWindow: 128000
+    tier: premium

config/samples/gateway_vertex_ai.yaml

@@ -0,0 +1,25 @@
+# Gateway for GCP Vertex AI with Claude.
+#
+# Prerequisites:
+#   kubectl create secret generic vertex-credentials \
+#     --from-file=GOOGLE_APPLICATION_CREDENTIALS_JSON="$HOME/.config/gcloud/application_default_credentials.json" \
+#     --from-literal=GCP_PROJECT_ID="$(gcloud config get-value project)" \
+#     --from-literal=GCP_LOCATION=global
+#
+# The credential Secret uses envFrom (no key field) because Vertex AI
+# requires GOOGLE_APPLICATION_CREDENTIALS_JSON as an env var name. The
+# whole Secret is exposed via envFrom, so GCP_PROJECT_ID (required by
+# goose's Vertex provider) and GCP_LOCATION ride along too.
+apiVersion: konveyor.io/v1alpha1
+kind: Gateway
+metadata:
+  name: gcp-vertex-ai
+spec:
+  provider: gcp-vertex-ai
+  endpoint: "https://global-aiplatform.googleapis.com"
+  credentialRef:
+    secretName: vertex-credentials
+  model:
+    name: claude-sonnet-4-5@20250929
+    contextWindow: 200000
+    tier: premium

config/samples/gateway_xai.yaml

@@ -0,0 +1,23 @@
+# Gateway for xAI (Grok).
+#
+# Prerequisites — create a Secret with your real API key:
+#   kubectl create secret generic grok-credentials \
+#     --from-literal=api-key="<your-xai-api-key>"
+apiVersion: konveyor.io/v1alpha1
+kind: Gateway
+metadata:
+  name: grok
+spec:
+  # Provider must be "xai" — the harness maps it to goose's xAI provider
+  # and forwards XAI_API_KEY.
+  provider: xai
+  # xAI API host. The controller's verification probe appends /v1/models;
+  # goose defaults XAI_HOST to https://api.x.ai/v1.
+  endpoint: "https://api.x.ai"
+  credentialRef:
+    secretName: grok-credentials
+    key: api-key
+  model:
+    name: grok-4
+    contextWindow: 256000
+    tier: premium