docs: Basic Concepts cleanup

.gitignore

@@ -125,4 +125,4 @@ Cargo.lock
 .direnv
 
 # Lerna debug
-lerna-debug.log
+lerna-debug.log

docs/docs/api-reference/starlark-reference/image-spec.md

@@ -0,0 +1,43 @@
+---
+title: ImageSpec
+sidebar_label: ImageSpec
+---
+
+The `ImageSpec` object constructor allows for providing detailed information about a container image for use in the [`ServiceConfig.image`](./service-config.md) property. It is most commonly used when pulling an image from a non-Dockerhub container repository.
+
+Signature
+---------
+
+```
+ImageSpec(
+    name, 
+    registry = "http://hub.docker.com", 
+    username = None, 
+    password = None,
+)
+```
+
+| Property | Description |
+| --- | --- |
+| **name**<br/>_string_ | The name of the container image that should be used. |
+| **registry**<br/>_string_ | The registry that the container should be pulled from. |
+| **username**<br/>_string_ | The username that will be used for connecting to the registry when pulling the image. |
+| **password**<br/>_string_ | The password that will be used for connecting to the registry when pulling the image. |
+
+Examples
+--------
+Starting a service called `my-service` from `my.registry.io` using a custom username and password:
+
+```python
+plan.add_service(
+    name = "my-service",
+    config = ServiceConfig(
+        image = ImageSpec(
+            name = "my.registry.io/some-org/some-image",
+            registry = "http://my.registry.io/",
+            username = "registry-user",
+            password = "SomePassword1!",
+        )
+    )
+)
+```

docs/docs/get-started/basic-concepts.md

@@ -5,41 +5,51 @@ slug: '/basic-concepts'
 sidebar_position: 4
 ---
 
-Package
+Enclave
 -----------
+An enclave is a logical grouping concept, a "walled garden" in which Kurtosis runs a microservice stack. Each Kurtosis instance can have many enclaves, and each enclave is isolated so that port and file conflicts don't occur. The enclaves and the services inside of them get mapped down into Docker or Kubernetes concepts, depending on your backend.
 
-A package defines the set up logic for a containerized backend. Packages can be accessed via Github locators.
+![enclaves.png](../../static/img/getting-started/enclaves.png)
 
-```console
-kurtosis run github.com/kurtosis-tech/basic-service-package
-```
+_Multiple enclaves can run on a single Kurtosis instance._
 
-Packages can accept a set of parameters, defined by the package author, which enable the package consumer to modify their deployed backend at a high-level without needing to know how to configure each individual service.
+Enclaves are cheap to create and cheap to destroy. They won't leave any resources hanging around after deletion.
 
-```console
-kurtosis run github.com/kurtosis-tech/basic-service-package \
-  '{"service_a_count": 2, 
-    "service_b_count": 2, 
-    "service_c_count": 1,
-    "party_mode": true}'
-```
+![delete-enclaves.png](../../static/img/getting-started/delete-enclaves.png)
 
-Enclave
+_Deleting enclaves is easy._
+
+Package
 -----------
+A package contains the setup logic for a microservice stack, and serves as a distribution mechanism.
+
+![package-catalog.png](../../static/img/getting-started/package-catalog.png)
+
+_Many packages are already available on the [Package Catalog](https://catalog.kurtosis.com/)._
+
+Packages can be composed together to form new microservices stacks, which can themselves be distributed as packages.
 
-An enclave is a "walled garden" in which Kurtosis runs a containerized backend. Enclaves can run anywhere that you have a Docker engine or a Kubernetes cluster. The main purposes of an enclave are resource isolation and "garbage collection". 
+Each package is identified by a "locator", which is a URL-like string uniquely identifying the package. For example, `github.com/kurtosis-tech/postgres-package`.
+
+Packages can can be configured using parameters, which allows package consumers to flex their microservice stack without knowing the inner workings of the stack.
+
+![package-params.png](../../static/img/getting-started/package-params.png)
+
+_Kurtosis provides tooling for authors to document their package parameters._
 
-With an "enclave remove" command (`kurtosis enclave rm`), you can destroy all of the resources used to set up your environment and leave nothing hanging around on your machine(s).
 
 Files Artifact
 -----------
-
 A files artifact is a set of files shipped with, or generated by, a package. Files artifacts are typically used for rendering configuration files that must be dynamically generated when an environment spins up, or for shipping static configuration files that must be shared across multiple services. 
 
-When you run a package, you can see the files artifacts that the package uses in the enclave output:
+When you run a package, you can see the files artifacts that the package created in the enclave.
+
+![files-artifacts.png](../../static/img/getting-started/files-artifacts.png)
+
+_Several files artifacts in an enclave._
+
+Files artifacts are just `.tgz` files, so exploring their contents is easy.
 
-```console
-kurtosis run github.com/kurtosis-tech/basic-service-package
-```
+![files-artifact-overview.png](../../static/img/getting-started/files-artifact-overview.png)
 
-![files-artifact-output-concepts.png](/img/home/files-artifact-output-concepts.png)
+_Contents of a files artifact called `prometheus-config`._

docs/docs/get-started/get-started.md

@@ -6,10 +6,10 @@ sidebar_position: 1
 hide_table_of_contents: true
 ---
 
-[Kurtosis](https://github.com/kurtosis-tech/kurtosis) is a tool for packaging and launching environments of containerized services where you want them, the way you want them, with one liners.
+[Kurtosis](https://github.com/kurtosis-tech/kurtosis) is a tool for packaging and launching microservice stacks where you want them, the way you want them, with one liners.
 
 - Get started with a [quickstart](quickstart.md) to launch an environment.
-- Dive deeper with [basic Kurtosis concepts](basic-concepts.md).
+- Learn about the [basic Kurtosis concepts](basic-concepts.md).
 - Write your own environment definition with a guide on [writing a package](write-your-first-package.md).
 
 To quickly see what Kurtosis feels like, check out the example snippets below:
@@ -79,4 +79,4 @@ kurtosis run github.com/kurtosis-tech/basic-service-package \
 
 ![service-c-partying.png](/img/home/service-c-k8s.png)
 
-</details>
+</details>

docs/docs/get-started/installing-the-cli.md

@@ -4,6 +4,7 @@ id: installing-the-cli
 sidebar_label: Install Kurtosis
 slug: /install
 sidebar_position: 2
+toc_max_header: 2
 ---
 
 <!---------- START IMPORTS ------------>

docs/docusaurus.config.js

@@ -88,15 +88,16 @@ const config = {
 						activeBasePath: '/sdk'
 					},
 					{
-						href: 'https://www.kurtosis.com/release-notes',
+						to: '/whats-new',
 						position: 'left',
-						label: 'Release Notes',
-					},
-					{
-						href: 'https://github.com/kurtosis-tech/kurtosis/issues/new?assignees=leeederek&labels=docs&template=docs-issue.yml',
-						position: 'right',
-						label: 'Report Docs Issue',
+						label: "What's New",
+						activeBasePath: '/whats-new'
 					},
+                    {
+                        href: 'https://github.com/kurtosis-tech/kurtosis/',
+                        position: 'right',
+                        className: 'header-github-link',
+                    }
 				],
 			},
 			footer: {

docs/src/css/custom.css

@@ -54,6 +54,22 @@ main {
   background-color: #111111;
 }
 
+.header-github-link::before {
+  content: '';
+  width: 24px;
+  height: 24px;
+  display: flex;
+  background-color: var(--ifm-navbar-link-color);
+  mask-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E");
+  transition: background-color var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
+}
+
+.header-github-link:hover::before {
+  background-color: var(--ifm-navbar-link-hover-color);
+}
+
+
  /*Stlying for search bar*/
 [data-theme='light'] .DocSearch {
   /* --docsearch-primary-color: var(--ifm-color-primary); */
@@ -93,4 +109,4 @@ main {
           var(--ifm-color-emphasis-200) 0%,
           var(--ifm-color-emphasis-100) 100%
   );
-}
+}