diff --git a/config/rbac/kustomization.yaml b/config/rbac/kustomization.yaml
index d192e78..d2f9efd 100644
--- a/config/rbac/kustomization.yaml
+++ b/config/rbac/kustomization.yaml
@@ -29,13 +29,13 @@ resources:
 # default, aiding admins in cluster management. Those roles are
 # not used by the koptan itself. You can comment the following lines
 # if you do not want those helpers be installed with your Project.
-- javaapp_admin_role.yaml
-- javaapp_editor_role.yaml
-- javaapp_viewer_role.yaml
-- dotnetapp_admin_role.yaml
-- dotnetapp_editor_role.yaml
-- dotnetapp_viewer_role.yaml
-- goapp_admin_role.yaml
-- goapp_editor_role.yaml
-- goapp_viewer_role.yaml
+  - javaapp_admin_role.yaml
+  - javaapp_editor_role.yaml
+  - javaapp_viewer_role.yaml
+  - dotnetapp_admin_role.yaml
+  - dotnetapp_editor_role.yaml
+  - dotnetapp_viewer_role.yaml
+  - goapp_admin_role.yaml
+  - goapp_editor_role.yaml
+  - goapp_viewer_role.yaml
 
diff --git a/docs/concepts/apps.md b/docs/concepts/apps.md
new file mode 100755
index 0000000..40aa549
--- /dev/null
+++ b/docs/concepts/apps.md
@@ -0,0 +1,36 @@
+# Apps
+
+Koptan provides application resources that represent application definitions at a higher level than native Kubernetes resources.
+
+## Supported App Resources
+
+Koptan currently defines:
+
+- `GoApp`
+- `DotnetApp`
+- `JavaApp`
+
+These types are defined in:
+
+- `api/v1alpha/goapp_types.go`
+- `api/v1alpha/dotnetapp_types.go`
+- `api/v1alpha/javaapp_types.go`
+
+## Purpose
+
+An App resource is intended to describe an application in a language-aware way.
+
+Instead of directly creating lower-level Kubernetes objects, users define an application using an App custom resource and let Koptan reconcile the desired state.
+
+## Why Separate App Types?
+
+Different languages often require different build or packaging behavior.
+
+For that reason, Koptan models them as separate resources rather than a single generic application type.
+
+## Related Resources
+
+An App resource is related to:
+
+- **Slipway**, which represents build-oriented workflow
+- **Voyage**, which represents deployment-oriented workflow
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
new file mode 100755
index 0000000..0be1cc9
--- /dev/null
+++ b/docs/concepts/index.md
@@ -0,0 +1,11 @@
+# Concepts
+
+This section introduces the main concepts in Koptan.
+
+Koptan centers around three resource groups:
+
+- **Apps**
+- **Slipway**
+- **Voyage**
+
+Together, these resources provide a structured way to define, build, and manage applications in Kubernetes.
diff --git a/docs/concepts/slipway.md b/docs/concepts/slipway.md
new file mode 100755
index 0000000..06d7230
--- /dev/null
+++ b/docs/concepts/slipway.md
@@ -0,0 +1,29 @@
+# Slipway
+
+`Slipway` is a Koptan resource associated with build-oriented workflow.
+
+## Purpose
+
+Slipway represents the part of the operator responsible for preparing or building application artifacts.
+
+In practical terms, this may include operations such as:
+
+- fetching source code
+- preparing build context
+- running language-specific build logic
+- producing deployable output
+
+## Implementation Clues in the Repository
+
+Relevant files include:
+
+- `api/v1alpha/slipway_types.go`
+- `internal/controller/slipway_controller.go`
+- `internal/controller/slipway_build.go`
+
+## Relationship to Other Resources
+
+Slipway works alongside:
+
+- **App** resources, which describe the application
+- **Voyage**, which represents the runtime or deployment stage
diff --git a/docs/concepts/voyage.md b/docs/concepts/voyage.md
new file mode 100755
index 0000000..2930965
--- /dev/null
+++ b/docs/concepts/voyage.md
@@ -0,0 +1,28 @@
+# Voyage
+
+`Voyage` is a Koptan resource associated with deployment-oriented workflow.
+
+## Purpose
+
+Voyage represents the stage where an application moves from build output into a running state on Kubernetes.
+
+Depending on how the operator evolves, this may include concerns such as:
+
+- rollout
+- runtime configuration
+- deployment reconciliation
+- lifecycle management
+
+## Implementation Clues in the Repository
+
+Relevant files include:
+
+- `api/v1alpha/voyage_types.go`
+- `internal/controller/voyage_controller.go`
+
+## Relationship to Other Resources
+
+Voyage works with:
+
+- **App** resources, which define the application
+- **Slipway**, which handles build-oriented workflow
diff --git a/docs/examples/app.md b/docs/examples/app.md
new file mode 100755
index 0000000..cdc5070
--- /dev/null
+++ b/docs/examples/app.md
@@ -0,0 +1,47 @@
+# App Example
+
+An App resource defines the source code repository for an application.
+
+Koptan currently supports multiple app kinds, including:
+
+- `GoApp`
+- `JavaApp`
+- `DotnetApp`
+
+The only required field is the source repository. The examples below show minimal definitions for each app type.
+
+=== "GoApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: GoApp
+    metadata:
+      name: feedme
+    spec:
+      source:
+        repo: https://github.com/example/feedme
+    ```
+
+=== "JavaApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: JavaApp
+    metadata:
+      name: orders-service
+    spec:
+      source:
+        repo: https://github.com/example/orders-service
+    ```
+
+=== "DotnetApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: DotnetApp
+    metadata:
+      name: payments-service
+    spec:
+      source:
+        repo: https://github.com/example/payments-service
+    ```
\ No newline at end of file
diff --git a/docs/examples/index.md b/docs/examples/index.md
new file mode 100755
index 0000000..1d5ba36
--- /dev/null
+++ b/docs/examples/index.md
@@ -0,0 +1,15 @@
+# Examples
+
+This section provides simple examples of the three main Koptan resources:
+
+- **App**: defines the application source repository
+- **Slipway**: connects an app to the build pipeline
+- **Voyage**: deploys the built application
+
+A typical Koptan workflow looks like this:
+
+1. Create an App resource
+2. Create a Slipway that references the App
+3. Create a Voyage that references the Slipway
+
+Use the pages in this section to see minimal working examples for each resource.
\ No newline at end of file
diff --git a/docs/examples/slipway.md b/docs/examples/slipway.md
new file mode 100755
index 0000000..77f0c49
--- /dev/null
+++ b/docs/examples/slipway.md
@@ -0,0 +1,51 @@
+# Slipway Example
+
+A Slipway connects an application to the build pipeline.
+
+It references an existing App using `name` and `kind`.
+
+## Examples
+
+=== "GoApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Slipway
+    metadata:
+      name: feedme
+    spec:
+      appRef:
+        name: feedme
+        kind: GoApp
+    ```
+
+=== "JavaApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Slipway
+    metadata:
+      name: orders-service
+    spec:
+      appRef:
+        name: orders-service
+        kind: JavaApp
+    ```
+
+=== "DotnetApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Slipway
+    metadata:
+      name: payments-service
+    spec:
+      appRef:
+        name: payments-service
+        kind: DotnetApp
+    ```
+
+## Apply a Slipway
+
+```bash
+kubectl apply -f slipway.yaml
\ No newline at end of file
diff --git a/docs/examples/voyage.md b/docs/examples/voyage.md
new file mode 100755
index 0000000..3022955
--- /dev/null
+++ b/docs/examples/voyage.md
@@ -0,0 +1,69 @@
+
+---
+
+# 📄 `docs/examples/voyage.md`
+
+```md
+# Voyage Example
+
+A Voyage deploys an application using a Slipway.
+
+It defines how the application runs inside the cluster.
+
+## Examples
+
+=== "Minimal"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Voyage
+    metadata:
+      name: feedme
+    spec:
+      slipwayRef:
+        name: feedme
+      port: 8080
+    ```
+
+=== "With Replicas & Env"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Voyage
+    metadata:
+      name: feedme
+    spec:
+      slipwayRef:
+        name: feedme
+      port: 8080
+      replicas: 2
+      env:
+        - name: ENV
+          value: production
+        - name: LOG_LEVEL
+          value: info
+    ```
+
+=== "With Health Check"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Voyage
+    metadata:
+      name: feedme
+    spec:
+      slipwayRef:
+        name: feedme
+      port: 8080
+      replicas: 2
+      healthCheck:
+        path: /health
+        port: 8080
+        initialDelaySeconds: 10
+        periodSeconds: 5
+    ```
+
+## Apply a Voyage
+
+```bash
+kubectl apply -f voyage.yaml
\ No newline at end of file
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
new file mode 100755
index 0000000..4f3e959
--- /dev/null
+++ b/docs/getting-started/index.md
@@ -0,0 +1,10 @@
+# Getting Started
+
+This section explains how to install Koptan and begin using its custom resources.
+
+It is intended for first-time users who want to:
+
+- install the operator
+- verify the CRDs are available
+- create an initial App resource
+- understand the basic usage flow
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100755
index 0000000..d5e113c
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,20 @@
+# Installation
+
+Koptan is installed as a Kubernetes operator.
+
+## Prerequisites
+
+Before installing Koptan, make sure you have:
+
+- a Kubernetes cluster
+- `kubectl` configured for that cluster
+- permissions to install CRDs and controller resources
+
+## Install the CRDs
+
+You can install the CRDs using the manifests under `config/crd`.
+
+Example:
+
+```bash
+kubectl apply -k config/crd
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
new file mode 100755
index 0000000..04b87b1
--- /dev/null
+++ b/docs/getting-started/quickstart.md
@@ -0,0 +1,24 @@
+
+# Quickstart
+
+This page shows a minimal example of using Koptan.
+
+## Step 1: Install the Operator
+
+Make sure Koptan and its CRDs are installed.
+
+See the Installation page for details.
+
+## Step 2: Create an App Resource
+
+Koptan supports multiple application resource types, including `GoApp`, `DotnetApp`, and `JavaApp`.
+
+A minimal example is shown below:
+
+```yaml
+apiVersion: koptan.felukka.sh/v1alpha1
+kind: GoApp
+metadata:
+  name: example-goapp
+spec:
+  {}
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100755
index 0000000..3352b60
--- /dev/null
+++ b/docs/overview.md
@@ -0,0 +1,38 @@
+# Overview
+
+Koptan is a Kubernetes operator for managing application delivery using custom resources.
+
+It provides a higher-level workflow for teams that want to define applications declaratively and let the operator handle reconciliation, build orchestration, and deployment-related flows.
+
+## Purpose
+
+Koptan is designed to reduce the amount of manual Kubernetes configuration needed to build and run applications.
+
+Instead of managing multiple low-level resources directly, users interact with a small set of Koptan resources:
+
+- App resources for describing applications
+- Slipway resources for build-related workflow
+- Voyage resources for deployment-related workflow
+
+## Problem Koptan Solves
+
+Application teams often need to combine:
+
+- source configuration
+- build logic
+- deployment configuration
+- Kubernetes resource management
+
+Koptan introduces operator-managed abstractions so this flow can be handled in a more consistent and reusable way.
+
+## Main Resources
+
+Koptan currently introduces the following main custom resources:
+
+- **GoApp**
+- **DotnetApp**
+- **JavaApp**
+- **Slipway**
+- **Voyage**
+
+See the Concepts section for more details.
diff --git a/mkdocs.yml b/mkdocs.yml
index 8088198..b8ec9a2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,53 +1,87 @@
----
-site_name: Koptan's Documentation
-repo_url: https://github.com/felukka/koptan
-site_url: https://koptan.felukka.org
-theme:
-  name: material
-  icon:
-    repo: fontawesome/brands/git-alt
-  # TODO: Replace with real logos
-  logo: assets/koptan.png
-  favicon: assets/koptan.png
-  font:
-    text: IBM Plex Sans Condensed
-    code: JetBrains Mono
-  features:
-    - navigation.footer
-    - search.highlight
-    - navigation.tabs
-    - navigation.top
-    - navigation.expand
-    - content.tabs.link
-  palette:
-    - scheme: default
-      primary: custom
-      toggle:
-        icon: material/weather-sunny
-        name: Dark mode
-    - scheme: slate
-      primary: custom
-      toggle:
-        icon: material/weather-night
-        name: Light mode
-markdown_extensions:
-  - attr_list
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.snippets
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
-  - pymdownx.tabbed:
-      alternate_style: true
-  - admonition
-  - pymdownx.details
-copyright: Copyright © 2026 Felukka.org
+site_name: Koptan's Documentation
+site_description: Documentation for Koptan, a Kubernetes operator for managing application builds and deployments
+repo_url: https://github.com/felukka/koptan
+repo_name: felukka/koptan
+site_url: https://koptan.felukka.org
+
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/git-alt
+  logo: assets/koptan.png
+  favicon: assets/koptan.png
+  font:
+    text: IBM Plex Sans Condensed
+    code: JetBrains Mono
+  features:
+    - navigation.footer
+    - navigation.tabs
+    - navigation.top
+    - navigation.expand
+    - navigation.sections
+    - navigation.indexes
+    - search.highlight
+    - search.suggest
+    - content.code.copy
+    - content.tabs.link
+    - toc.follow
+  palette:
+    - scheme: default
+      primary: custom
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - scheme: slate
+      primary: custom
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+
+markdown_extensions:
+  - attr_list
+  - admonition
+  - pymdownx.details
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Overview: overview.md
+
+  - Concepts:
+      - Overview: concepts/index.md
+      - Apps: concepts/apps.md
+      - Slipway: concepts/slipway.md
+      - Voyage: concepts/voyage.md
+
+  - Getting Started:
+      - Overview: getting-started/index.md
+      - Installation: getting-started/installation.md
+      - Quickstart: getting-started/quickstart.md
+
+  - Examples:
+      - Overview: examples/index.md
+      - App Example: examples/app.md
+      - Slipway Example: examples/slipway.md
+      - Voyage Example: examples/voyage.md
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/felukka/koptan
+
+copyright: Copyright © 2026 Felukka.org
\ No newline at end of file