docs: add introduction section and improve content structure (#8)

- Add Introduction section with 'What is Forkspacer' and Core Concepts pages
- Reorganize homepage cards for better flow (show examples first, then explain)
- Add context to Quick Start explaining module definitions
- Simplify Helm installation instructions
- Update navigation to include Introduction as first section

Author: joshuasequeira19

astro.config.mjs

@@ -11,7 +11,14 @@ export default defineConfig({
 			social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/forkspacer' }],
 			sidebar: [
 				{
-					label: 'Guides',
+					label: 'Introduction',
+					items: [
+						{ label: 'What is Forkspacer?', link: '/introduction/overview/' },
+						{ label: 'Core Concepts', link: '/introduction/concepts/' },
+					],
+				},
+				{
+					label: 'Getting Started',
 					autogenerate: { directory: 'guides' },
 				},
 				{

src/content/docs/development/custom-module.md

@@ -5,8 +5,6 @@ sidebar:
   order: 2
 ---
 
-# Custom Module Development
-
 Forkspacer supports custom modules that allow you to extend the operator with custom resource management logic. Custom modules enable you to integrate third-party tools, implement custom deployment strategies, or handle specialized workloads beyond the built-in Helm support.
 
 ## What are Custom Modules?
@@ -32,6 +30,7 @@ Custom modules expose an HTTP server that the operator calls to manage Module li
 #### Required Endpoints
 
 **Health Check:**
+
 ```
 GET /health
 Response: 200 OK
@@ -44,6 +43,7 @@ Response: 200 OK
 ```
 
 **Install:**
+
 ```
 POST /install
 Content-Type: application/json
@@ -52,6 +52,7 @@ Response: 201 Created (on success) or 400 Bad Request (on failure)
 ```
 
 **Uninstall:**
+
 ```
 POST /uninstall
 Content-Type: application/json
@@ -60,6 +61,7 @@ Response: 204 No Content (on success) or 400 Bad Request (on failure)
 ```
 
 **Sleep:**
+
 ```
 POST /sleep
 Content-Type: application/json
@@ -68,6 +70,7 @@ Response: 200 OK (on success) or 400 Bad Request (on failure)
 ```
 
 **Resume:**
+
 ```
 POST /resume
 Content-Type: application/json
@@ -95,6 +98,7 @@ go mod init my-module
 ```
 
 **Example `go.mod`:**
+
 ```go
 module my-module
 
@@ -724,6 +728,7 @@ func (h *Handler) Health(w http.ResponseWriter, r *http.Request) {
 ## Complete Example
 
 See the complete example custom module in the repository:
+
 - [Example Custom Module](https://github.com/forkspacer/modules/tree/main/custom/example)
 
 ## Next Steps

src/content/docs/development/overview.md

@@ -5,8 +5,6 @@ sidebar:
   order: 1
 ---
 
-# Development Overview
-
 This guide covers the development workflow for contributing to the Forkspacer operator, including setting up your development environment, building, testing, and running the operator locally.
 
 ## Prerequisites
@@ -61,11 +59,13 @@ make dev-host
 ```
 
 This runs the operator against your current kubeconfig context. It's useful for:
+
 - Quick testing of controller logic
 - Debugging with your IDE
 - Fast iteration without image builds
 
 **Important Notes:**
+
 - **Webhooks are disabled** - The operator runs with `ENABLE_WEBHOOKS=false`, so validation and defaulting webhooks won't be active
 - **Use `local` connection type** - When creating Workspaces in dev-host mode, use `type: local` instead of `type: in-cluster` for the connection configuration
 - Your kubeconfig must point to a running cluster (Kind, minikube, etc.)
@@ -81,7 +81,7 @@ metadata:
 spec:
   type: kubernetes
   connection:
-    type: local  # Use 'local' when running with dev-host
+    type: local # Use 'local' when running with dev-host
     secretReference:
       name: local
 ```
@@ -95,6 +95,7 @@ make dev-kind
 ```
 
 This will:
+
 1. Delete any existing `operator-dev` Kind cluster
 2. Create a fresh Kind cluster
 3. Install cert-manager
@@ -104,6 +105,7 @@ This will:
 7. Deploy the operator
 
 **Benefits of Kind Development:**
+
 - Isolated environment that won't affect other clusters
 - Tests the full deployment process
 - Validates webhook configurations
@@ -177,6 +179,7 @@ make test-e2e
 ```
 
 This will:
+
 1. Create a Kind cluster named `operator-test-e2e` (if it doesn't exist)
 2. Run e2e tests using Ginkgo
 3. Clean up the Kind cluster after tests complete
@@ -247,12 +250,14 @@ Platforms: `linux/arm64`, `linux/amd64`, `linux/s390x`, `linux/ppc64le`
 ### Debugging
 
 1. **Enable verbose logging**: Set environment variable before running:
+
    ```bash
    export LOG_LEVEL=debug
    make dev-host
    ```
 
 2. **Use delve for debugging**:
+
    ```bash
    dlv debug ./cmd/main.go
    ```

src/content/docs/guides/installation.md

@@ -2,20 +2,21 @@
 title: Installation
 description: How to install the Forkspacer operator in your Kubernetes cluster
 sidebar:
-    order: 1
+  order: 1
 ---
 
-# Installing Forkspacer
-
-This guide walks you through installing the Forkspacer operator in your Kubernetes cluster.
+This guide walks you through installing the Forkspacer operator in your Kubernetes cluster using Helm (recommended).
 
 ## Prerequisites
 
 - Kubernetes cluster (v1.20 or later)
 - `kubectl` configured to access your cluster
+- `helm` (v3.0 or later)
 - Cluster admin permissions
 
-## Installation Steps
+## Helm Installation
+
+Forkspacer is installed using Helm charts for flexible and manageable deployments.
 
 ### 1. Install cert-manager
 
@@ -33,31 +34,40 @@ kubectl wait --for=condition=available --timeout=300s deployment/cert-manager-ca
 kubectl wait --for=condition=available --timeout=300s deployment/cert-manager-webhook -n cert-manager
 ```
 
-### 2. Deploy Forkspacer
+### 2. Deploy Forkspacer with Helm
 
-Install the Forkspacer operator using Helm:
+Add the Forkspacer Helm repository:
 
 ```bash
-# Add the Forkspacer Helm repository
 helm repo add forkspacer https://forkspacer.github.io/forkspacer
 helm repo update
+```
+
+<!-- Choose your installation method: -->
+
+<!-- **Option A: Operator Only (Minimal)** -->
+
+**Operator Only (Minimal)**
+
+Install just the core operator for managing workspaces and modules:
 
-# Install Forkspacer
+```bash
 helm install forkspacer forkspacer/forkspacer \
   --namespace forkspacer-system \
   --create-namespace
 ```
 
-For advanced configuration options:
+<!-- **Option B: With Web UI and API Server**
+
+Install with the web UI and API server enabled for a complete management experience:
 
 ```bash
-# Install with custom values
 helm install forkspacer forkspacer/forkspacer \
-  --namespace forkspacer-system \
-  --create-namespace \
   --set operator-ui.enabled=true \
-  --set ingress.enabled=true
-```
+  --set api-server.enabled=true \
+  --namespace forkspacer-system \
+  --create-namespace
+``` -->
 
 ### 3. Verify Installation
 

src/content/docs/guides/quick-start.md

@@ -2,11 +2,9 @@
 title: Quick Start
 description: Get started with Forkspacer in 5 minutes
 sidebar:
-    order: 2
+  order: 2
 ---
 
-# Quick Start Guide
-
 This guide will help you create your first workspace and deploy a module in just a few minutes.
 
 ## Prerequisites
@@ -86,6 +84,26 @@ NAME    WORKSPACE   PHASE   AGE
 redis   default     ready   45s
 ```
 
+## Understanding What You Created
+
+Before we continue, let's understand what just happened:
+
+You now have three components working together:
+
+1. **Workspace** (`default`): An isolated Kubernetes environment managed by Forkspacer
+2. **Module** (`redis`): A Kubernetes CRD that declares "install Redis in the default workspace"
+3. **Module Definition**: A YAML template hosted on GitHub that describes how to install Redis using a Helm chart
+
+When you created the Module, the Forkspacer operator:
+
+1. Detected the new Module CRD
+2. Fetched the module definition from the GitHub URL
+3. Parsed the Helm configuration in that definition
+4. Installed Redis using the Helm chart specified in the definition
+5. Applied your configuration values (`replicaCount`, `version`)
+
+> **What's in that URL?** The GitHub URL points to a [module definition](/introduction/concepts/#module-definition) - a reusable template that describes how to install Redis. Module definitions can be shared across teams and stored in Git repositories. [View the Redis module definition →](https://raw.githubusercontent.com/forkspacer/modules/refs/heads/main/redis/1.0.0/module.yaml)
+
 ## Step 3: Verify the Deployment
 
 Check the pods created by the module:
@@ -155,16 +173,18 @@ kubectl delete workspace default
 ### Common Use Cases
 
 **Development Environments:**
+
 ```yaml
 # Auto-hibernate outside business hours to save costs
 spec:
   autoHibernation:
     enabled: true
-    schedule: "0 18 * * 1-5"      # 6 PM weekdays
-    wakeSchedule: "0 8 * * 1-5"   # 8 AM weekdays
+    schedule: "0 18 * * 1-5" # 6 PM weekdays
+    wakeSchedule: "0 8 * * 1-5" # 8 AM weekdays
 ```
 
 **Testing Environments:**
+
 ```yaml
 # Fork from production workspace
 spec:
@@ -175,6 +195,7 @@ spec:
 ```
 
 **Staging Environments:**
+
 ```yaml
 # Deploy from HTTP-hosted resource definitions
 spec: