Add project documentation for the developer-quickstart (#10)

Introduce Hugo-compatible docs covering installation, prerequisites,
architecture, accessing services, overlays, metrics, troubleshooting
and uninstall.

* Add docs folder for content pages and overlays subsection
* Add docs/preview.sh script for local Hugo preview and static builds
* Add local preview instructions to README.md
* Move repository structure section from README into docs
* Update .gitignore to exclude .docs-preview/ directory
* Refactor readme so detailed installation instructions point to docs

Signed-off-by: Thomas Cooper <code@tomcooper.dev>

Author: tomncooper

.gitignore

@@ -6,4 +6,7 @@
 *.iml
 
 ### Mac OS ###
-**.DS_Store
+**.DS_Store
+
+# Hugo local preview site (generated by docs/preview.sh)
+.docs-preview/

README.md

@@ -6,22 +6,17 @@ A Kustomize-based repository for deploying the StreamsHub event-streaming stack
 
 ## What Gets Deployed
 
-| Component | Namespace | Description |
-|-----------|-----------|-------------|
-| Strimzi Kafka Operator | `strimzi` | Manages Kafka clusters via CRDs |
-| Kafka cluster (`dev-cluster`) | `kafka` | Single-node Kafka for development |
-| Apicurio Registry Operator | `apicurio-registry` | Manages schema registry instances |
-| Apicurio Registry instance | `apicurio-registry` | In-memory schema registry |
-| StreamsHub Console Operator | `streamshub-console` | Manages console instances |
-| StreamsHub Console instance | `streamshub-console` | Web UI for Kafka management |
+The stack deploys Strimzi Kafka, Apicurio Registry, and StreamsHub Console operators along with their operand instances. 
+Optional [overlays](docs/overlays/_index.md) add components such as Prometheus metrics.
 
-> **Optional:** The [metrics overlay](#install-with-metrics) adds Prometheus Operator, a Prometheus instance, and Kafka metrics collection via PodMonitors.
+See [What Gets Deployed](docs/_index.md#what-gets-deployed) for the full component breakdown.
 
 ## Prerequisites
 
-- `kubectl` v1.27 or later (for Kustomize v5.0 `labels` transformer support)
-- A running Kubernetes cluster (minikube, KIND, etc.)
-- An Ingress controller for StreamsHub Console access (e.g. `minikube addons enable ingress`)
+- `kubectl` v1.27 or later
+- A running Kubernetes cluster (minikube, KIND, etc.) with an ingress controller 
+
+See [Prerequisites](docs/prerequisites.md) for full requirements and cluster setup instructions.
 
 ## Quick-Start Install
 
@@ -33,232 +28,75 @@ curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/
 
 This script installs operators, waits for them to become ready, then deploys the operands.
 
-### Configuration
-
-The install script accepts the following environment variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `REPO` | `streamshub/developer-quickstart` | GitHub repository path |
-| `REF` | `main` | Git ref, branch, or tag |
-| `OVERLAY` | *(empty)* | Overlay to apply (e.g. `metrics`) |
-| `TIMEOUT` | `120s` | `kubectl wait` timeout |
-
-Example with a pinned version:
-
-```shell
-curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | REF=v1.0.0 bash
-```
-
-### Install with Metrics
-
-Deploy the stack with Prometheus metrics collection:
+To install with an overlay (e.g. metrics):
 
 ```shell
 curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | OVERLAY=metrics bash
 ```
 
-This adds the Prometheus Operator and a Prometheus instance (namespace: `monitoring`), enables Kafka metrics via [Strimzi Metrics Reporter](https://strimzi.io/docs/operators/latest/deploying#proc-metrics-kafka-str), and wires Console to display metrics.
-
-## Manual Install
-
-If you prefer to control each step, the stack is installed in two phases:
-
-### Phase 1 — Operators and CRDs
-
-```shell
-kubectl apply -k 'https://github.com/streamshub/developer-quickstart//overlays/core/base?ref=main'
-```
-
-Wait for the operators to become ready:
-
-```shell
-kubectl wait --for=condition=Available deployment/strimzi-cluster-operator -n strimzi --timeout=120s
-kubectl wait --for=condition=Available deployment/apicurio-registry-operator -n apicurio-registry --timeout=120s
-kubectl wait --for=condition=Available deployment/streamshub-console-operator -n streamshub-console --timeout=120s
-```
-
-### Phase 2 — Operands
+See [Installation](docs/installation.md) for configuration options, manual install steps, and installing from a local checkout.
 
-```shell
-kubectl apply -k 'https://github.com/streamshub/developer-quickstart//overlays/core/stack?ref=main'
-```
+## Accessing Services
 
-### Manual Install with Metrics
-
-To include the metrics overlay, use the `overlays/metrics` paths instead of `overlays/core`.
+After installation, use port-forwarding to access the Console:
 
 ```shell
-# Phase 1
-kubectl create -k 'https://github.com/streamshub/developer-quickstart//overlays/metrics/base?ref=main'
-kubectl wait --for=condition=Available deployment/prometheus-operator -n monitoring --timeout=120s
-kubectl wait --for=condition=Available deployment/strimzi-cluster-operator -n strimzi --timeout=120s
-kubectl wait --for=condition=Available deployment/apicurio-registry-operator -n apicurio-registry --timeout=120s
-kubectl wait --for=condition=Available deployment/streamshub-console-operator -n streamshub-console --timeout=120s
-
-# Phase 2
-kubectl apply -k 'https://github.com/streamshub/developer-quickstart//overlays/metrics/stack?ref=main'
+kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80
 ```
 
-## Accessing the Console
-
-### Minikube
+Open [http://localhost:8090](http://localhost:8090) in your browser.
 
-When using minikube, (if you didn't enable it when you created the minikube cluster) enable the ingress addon and run `minikube tunnel`:
-
-```bash
-minikube addons enable ingress
-minikube tunnel
-```
-
-Then use port-forwarding to access the console:
-
-```bash
-kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8080:80
-```
-
-Open [http://localhost:8080](http://localhost:8080) in your browser.
-
-### Kind
-
-When using Kind, create the cluster with ingress-ready port mappings:
-
-```bash
-cat <<EOF | kind create cluster --config=-
-kind: Cluster
-apiVersion: kind.x-k8s.io/v1alpha4
-nodes:
-  - role: control-plane
-    kubeadmConfigPatches:
-      - |
-        kind: InitConfiguration
-        nodeRegistration:
-          kubeletExtraArgs:
-            node-labels: "ingress-ready=true"
-    extraPortMappings:
-      - containerPort: 80
-        hostPort: 80
-        protocol: TCP
-      - containerPort: 443
-        hostPort: 443
-        protocol: TCP
-EOF
-```
-
-Then deploy an ingress controller (e.g. ingress-nginx):
-
-```bash
-kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.12.1/deploy/static/provider/kind/deploy.yaml
-kubectl wait --namespace ingress-nginx \
-  --for=condition=Ready pod \
-  --selector=app.kubernetes.io/component=controller \
-  --timeout=120s
-```
-
-Use port-forwarding to access the console:
-
-```bash
-kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8080:80
-```
-
-Open [http://localhost:8080](http://localhost:8080) in your browser.
+See [Accessing Services](docs/accessing-services.md) for Kafka, Apicurio Registry access, and platform-specific instructions.
 
 ## Teardown
 
-### Using the Uninstall Script
-
-The uninstall script handles safe teardown with shared-cluster safety checks:
+Remove the quick-start stack:
 
 ```shell
 curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/uninstall.sh | bash
-
-# If installed with the metrics overlay:
-curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/uninstall.sh | OVERLAY=metrics bash
 ```
 
-The script:
-1. Deletes operand custom resources and waits for finalizers to complete
-2. Checks each operator group for non-quick-start CRs on the cluster
-3. Fully removes operator groups with no shared CRDs
-4. For shared operator groups, removes only the operator deployment (retaining CRDs)
-5. Reports any retained groups and remaining resources
-
-### Manual Teardown
-
-**Phase 1 — Delete operands:**
-
-```shell
-kubectl delete -k 'https://github.com/streamshub/developer-quickstart//overlays/core/stack?ref=main'
-```
-
-Wait for all custom resources to be fully removed before proceeding.
-
-**Phase 2 — Delete operators and CRDs:**
-
-> **Warning:** On shared clusters, deleting CRDs will cascade-delete ALL custom resources of that type cluster-wide. Check for non-quick-start resources first:
-> ```shell
-> kubectl get kafkas -A --selector='!app.kubernetes.io/part-of=streamshub-developer-quickstart'
-> ```
-
-```shell
-kubectl delete -k 'https://github.com/streamshub/developer-quickstart//overlays/core/base?ref=main'
-```
+See [Uninstallation](docs/uninstallation.md) for metrics overlay uninstall, manual teardown, and shared-cluster safety details.
 
-For the metrics overlay, use `overlays/metrics/base` and `overlays/metrics/stack` instead.
+## Documentation
 
-### Finding Quick-Start Resources
+Full documentation is available in the [`docs/`](docs/) directory:
 
-All resources carry the label `app.kubernetes.io/part-of=streamshub-developer-quickstart`:
-
-```shell
-kubectl get all -A -l app.kubernetes.io/part-of=streamshub-developer-quickstart
-kubectl get crds,clusterroles,clusterrolebindings -l app.kubernetes.io/part-of=streamshub-developer-quickstart
-```
+- [Prerequisites](docs/prerequisites.md) — requirements and cluster setup
+- [Installation](docs/installation.md) — all install methods, configuration, and local development
+- [Accessing Services](docs/accessing-services.md) — Console, Kafka, and Registry access
+- [Architecture](docs/architecture.md) — deployment model, Kustomize structure, versioning
+- [Overlays](docs/overlays/_index.md) — optional extensions (metrics, etc.)
+- [Uninstallation](docs/uninstallation.md) — safe teardown on any cluster
+- [Troubleshooting](docs/troubleshooting.md) — common issues and diagnostics
 
 ## Development
 
-### Updating Component Versions
-
-Use the `update-version.sh` script to update component versions:
+For development workflows including updating component versions and testing scripts locally, see:
+- [Updating Component Versions](docs/architecture.md#updating-component-versions)
+- [Install from a Local Checkout](docs/installation.md#install-from-a-local-checkout)
 
-```shell
-# List available versions
-./update-version.sh --list strimzi
-
-# Preview changes
-./update-version.sh --dry-run strimzi 0.52.0
+### Previewing Documentation Locally
 
-# Check if a release exists
-./update-version.sh --check apicurio-registry 3.2.0
+The `docs/` directory contains the project documentation. To preview it locally with Hugo:
 
-# Update a component
-./update-version.sh strimzi 0.52.0
+```shell
+./docs/preview.sh
 ```
 
-Supported components: `strimzi`, `apicurio-registry`, `streamshub-console`, `prometheus-operator`
-
-### Testing scripts locally
+This starts a local server at [http://localhost:1313/docs/](http://localhost:1313/docs/) with live-reload. 
+Press `Ctrl+C` to stop.
 
-When developing changes to the kustomization files, use the `LOCAL_DIR` environment
-variable to point the install and uninstall scripts at your local checkout instead
-of the remote GitHub repository:
+To generate static HTML instead:
 
 ```shell
-# Install from local repo
-LOCAL_DIR=. ./install.sh
-
-# Uninstall from local repo
-LOCAL_DIR=. ./uninstall.sh
+./docs/preview.sh build
 ```
 
-When `LOCAL_DIR` is set, `REPO` and `REF` are ignored — the scripts resolve
-kustomization paths relative to the given directory.
-
-You can also provide an absolute path:
+The output is written to `.docs-preview/public/`.
 
-```shell
-LOCAL_DIR=/home/user/repos/developer-quickstart ./install.sh
-```
+**Requirements:** `hugo`, `git`, and `go` must be installed. 
+The script handles theme fetching and site configuration automatically.
 
 ## Testing
 
@@ -327,29 +165,3 @@ The scripts accept configuration via environment variables:
 | `CONDITION_OVERRIDES` | VerifyInstall | *(empty)* | Space-separated `apiGroup=Condition` pairs |
 | `PLATFORMS` | ComputeTestMatrix | `minikube kind` | Space-separated list of target platforms |
 | `LOG_TAIL_LINES` | Debug | `30` | Number of log lines to tail per pod |
-
-## Repository Structure
-
-```
-components/                         # Reusable Kustomize components
-├── core/                           # Core stack component
-│   ├── base/                       # Operators & CRDs
-│   │   ├── strimzi-operator/       # Strimzi Kafka Operator
-│   │   ├── apicurio-registry-operator/  # Apicurio Registry Operator
-│   │   └── streamshub-console-operator/ # StreamsHub Console Operator
-│   └── stack/                      # Operands (Custom Resources)
-│       ├── kafka/                  # Single-node Kafka cluster
-│       ├── apicurio-registry/      # In-memory registry instance
-│       └── streamshub-console/     # Console instance
-└── metrics/                        # Prometheus metrics component
-    ├── base/                       # Prometheus Operator
-    └── stack/                      # Prometheus instance, PodMonitors, patches
-
-overlays/                           # Deployable configurations
-├── core/                           # Default install (core only)
-│   ├── base/                       # Phase 1: Operators & CRDs
-│   └── stack/                      # Phase 2: Operands
-└── metrics/                        # Core + Prometheus metrics
-    ├── base/                       # Phase 1: Operators & CRDs + Prometheus Operator
-    └── stack/                      # Phase 2: Operands + Prometheus instance & monitors
-```

docs/_index.md

@@ -0,0 +1,47 @@
++++
+title = 'Developer Quick-Start'
+linkTitle = 'Developer Quick-Start'
+weight = 0
+[[cascade]]
+    type = 'docs'
++++
+
+# Developer Quick-Start
+
+Please make sure you have all the [prerequisites](prerequisites.md) covered first.
+Then you can deploy a complete, open-source, event-streaming stack on your local Kubernetes cluster (e.g. MiniKube, KIND) with a single command:
+
+```shell
+curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | bash
+```
+
+The script installs operators, waits for readiness, then deploys all services. 
+The full stack is typically ready in under five minutes.
+
+> **Note:** This is a **development-only** configuration. Resource limits, security settings, and storage are not suitable for production use.
+
+## What Gets Deployed
+
+| Component                     | Namespace            | Description                       |
+|-------------------------------|----------------------|-----------------------------------|
+| Strimzi Kafka Operator        | `strimzi`            | Manages Kafka clusters via CRDs   |
+| Kafka cluster (`dev-cluster`) | `kafka`              | Single-node Kafka for development |
+| Apicurio Registry Operator    | `apicurio-registry`  | Manages schema registry instances |
+| Apicurio Registry             | `apicurio-registry`  | In-memory schema registry         |
+| StreamsHub Console Operator   | `streamshub-console` | Manages console instances         |
+| StreamsHub Console            | `streamshub-console` | Web UI for Kafka management       |
+
+Optional [overlays](overlays/_index.md) can extend the core stack with additional components such as Prometheus metrics. Install with an overlay by setting the `OVERLAY` variable:
+
+```shell
+curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | OVERLAY=<name> bash
+```
+
+## Next Steps
+
+- [Prerequisites](prerequisites.md) — what you need before installing.
+- [Installation](installation.md) — all installation methods and options.
+- [Accessing Services](accessing-services.md) — open the Console, connect to Kafka.
+- [Overlays](overlays/) - look at the what additional components and features can be added with the provided overlays.
+- [Uninstallation](uninstallation.md) — safe teardown on any cluster.
+- [Troubleshooting](troubleshooting.md) - help with common issues.