Merge pull request #2208 from helderco/docs-types

docs: Add types reference

docs/references/1222-core-actions-reference.md

@@ -20,7 +20,6 @@ The following core actions are available:
 | `#Merge`     | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Merge multiple filesystem trees                                       |
 | `#Mkdir`     | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Create a directory in a filesystem tree                               |
 | `#ReadFile`  | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Read a file from a filesystem tree                                    |
-| `#Scratch`   | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Create an empty filesystem tree                                       |
 | `#Source`    | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Access the source for the current CUE package                         |
 | `#Subdir`    | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Read a subdirectory from a filesystem tree                            |
 | `#WriteFile` | [fs.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/fs.cue) | Write a file to a filesystem tree                                     |

docs/references/1234-dagger-types-reference.md

@@ -0,0 +1,41 @@
+---
+slug: /1234/dagger-types-reference
+displayed_sidebar: "0.2"
+---
+
+# Dagger Types Reference
+
+Dagger Types are primitives that hold internal references to values stored in the Dagger Engine. They extend the CUE type system and can be used in [Dagger Actions](../core-concepts/1221-action.md). Their definitions can be imported from the `dagger.io/dagger` package.
+
+The following types are available:
+
+| Definition     | File                                                                                        | Description                                           |
+| :------------- | :------------------------------------------------------------------------------------------ | :---------------------------------------------------- |
+| `#FS`          | [types.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/types.cue)    | Reference to a filesystem tree                        |
+| `#Secret`      | [types.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/types.cue)    | Secure reference to an external secret                |
+| `#Socket`      | [types.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/types.cue)    | Reference to a network socket: unix or npipe          |
+
+And there's a special instance of a Dagger Type:
+
+| Definition     | File                                                                                        | Type  | Description                                   |
+| :------------- | :------------------------------------------------------------------------------------------ | : --- | :-------------------------------------------- |
+| `#Scratch`     | [values.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/values.cue)  | `#FS` | An empty filesystem tree                      |
+
+## Data structures
+
+There's also some data structures that are tightly coupled to [core actions](./1222-core-actions-reference.md). Their definitions are in the `dagger.io/dagger/core` package.
+
+### Related to mounts
+
+| Definition     | File                                                                                             | Description                                           |
+| :------------- | :----------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
+| `#Mount`       | [core/exec.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/exec.cue) | Transient filesystem mount                            |
+| `#CacheDir`    | [core/exec.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/exec.cue) | A (best effort) persistent cache dir                  |
+| `#TempDir`     | [core/exec.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/core/exec.cue) | A temporary directory for command execution           |
+
+### Related to container images
+
+| Definition     | File                                                                                             | Description                                           |
+| :------------- | :----------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
+| `#ImageConfig` | [core/image.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/image.cue)    | Container image config                                |
+| `#HealthCheck` | [core/image.cue](https://github.com/dagger/dagger/blob/v0.2.4/pkg/dagger.io/dagger/image.cue)    | Container health check                                |

pkg/dagger.io/dagger/types.cue

@@ -10,11 +10,6 @@ package dagger
 	$dagger: fs: _id: string | null
 }
 
-// An empty directory
-#Scratch: #FS & {
-	$dagger: fs: _id: null
-}
-
 // A reference to an external secret, for example:
 //  - A password
 //  - A SSH private key

pkg/dagger.io/dagger/values.cue

@@ -0,0 +1,6 @@
+package dagger
+
+// An empty filesystem tree
+#Scratch: #FS & {
+	$dagger: fs: _id: null
+}

website/sidebars.js

@@ -79,6 +79,7 @@ module.exports = {
       collapsed: false,
       items: [
         "references/core-actions-reference",
+        "references/dagger-types-reference",
       ],
     },
     {