tilebox · lukasbindreiter · Jun 15, 2026 · Jun 15, 2026
diff --git a/.agents/skills/creating-documentation-graphics/SKILL.md b/.agents/skills/creating-documentation-graphics/SKILL.md
diff --git a/.../creating-documentation-graphics/references/best-practice-technical-sketch.jpeg b/.../creating-documentation-graphics/references/best-practice-technical-sketch.jpeg
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,5 +1,10 @@
 {
   "editor.formatOnSave": true,
-  "editor.rulers": [120],
+  "editor.rulers": [
+    120
+  ],
   "files.insertFinalNewline": true,
+  "json.schemaDownload.trustedDomains": {
+    "https://mintlify.com/docs.json": true
+  },
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -101,18 +101,18 @@ Local setup and validation commands:
 
 ```bash
 # install tooling
-npm i -g mintlify
+npm i -g mint
 vale sync
 pre-commit install
 
 # run docs locally
-mintlify dev
+mint dev
 
 # lint prose
 vale .
 
 # check broken links
-mintlify broken-links
+mint broken-links
 
 # optional: run all hooks
 pre-commit run --all-files
@@ -124,11 +124,13 @@ CI notes:
 2. CI installs `mdx2vast` before running Vale.
 3. CI runs `vale sync && vale .` and `mintlify broken-links`.
 
-## Diagrams And Assets
+## Documentation Graphics And Workflow DAG Assets
 
-Workflow diagrams under `assets/workflows/diagrams/` are generated from `.d2` files via `generate.py`.
+For normal documentation graphics, use the `creating-documentation-graphics` skill and generate PNGs with painter from the start. This applies to architecture diagrams, concept diagrams, release/deployment diagrams, data-flow diagrams, and other visual explainers embedded in docs pages.
 
-When updating workflow diagrams:
+Do not hand-author SVGs for normal documentation graphics just because they seem more maintainable. The intended output is a light/dark PNG pair, usually named like `name-light.png` and `name-dark.png`, referenced with the standard Mintlify light/dark image pattern.
+
+The D2/SVG workflow under `assets/workflows/diagrams/` is only for workflow DAG diagrams, such as task graphs, task-state DAGs, retry DAGs, optional-subtask trees, or existing diagrams with `.d2` sources. When updating those workflow DAG diagrams:
 
 1. Edit the `.d2` source.
 2. Regenerate SVG assets with `python generate.py` from `assets/workflows/diagrams/`.

diff --git a/agentic-development/agent-skills.mdx b/agentic-development/agent-skills.mdx
@@ -32,7 +32,8 @@ Tilebox skills cover common agent workflows around the CLI, datasets, workflows,
 | `managing-tilebox-datasets` | Creating schemas, updating metadata, and querying datasets |
 | `managing-tilebox-jobs` | Submitting jobs, monitoring status, reading logs, and inspecting spans |
 | `working-with-tilebox-automations` | Working with triggers, automations, and storage locations |
-| `writing-tilebox-workflows` | Writing Tilebox workflow tasks and task runners |
+| `writing-tilebox-workflows` | Writing workflow task classes, task graphs, runner definitions, caches, logs, and spans |
+| `releasing-tilebox-workflows` | Creating `tilebox.workflow.toml`, building releases, publishing releases, deploying to clusters, and running release runners |
 
 ## How to use skills with agents
 
@@ -43,3 +44,5 @@ Load the relevant Tilebox skills. Use the Tilebox CLI to submit a Sentinel-2 mos
 ```
 
 Skills work best with the Tilebox CLI. The CLI gives the agent repeatable terminal commands, and skills tell it how to combine those commands safely. Use MCP as an alternative when the agent runs in a web or chat environment without practical terminal access.
+
+For Python workflow release work, ask the agent to use both `writing-tilebox-workflows` and `releasing-tilebox-workflows`. The typical loop is to edit tasks, build and publish a release, deploy it to a development cluster, run `tilebox runner start`, submit a test job, and inspect logs or spans before iterating.
diff --git a/agentic-development/overview.mdx b/agentic-development/overview.mdx
@@ -26,6 +26,9 @@ Tilebox supports agents through a CLI-based setup. The CLI gives agents a determ
   <Card title="Agent Skills" icon="wand-magic-sparkles" href="/agentic-development/agent-skills">
     Install Tilebox skills that teach agents how to work with Tilebox tools.
   </Card>
+  <Card title="Agentic workflow iteration" icon="robot" href="/guides/workflows/agentic-workflow-iteration">
+    Use an agent to edit workflow code, publish releases, deploy them to a dev cluster, and inspect jobs.
+  </Card>
 </Columns>
 
 ## Recommended setup

diff --git a/agentic-development/tilebox-cli.mdx b/agentic-development/tilebox-cli.mdx
@@ -24,7 +24,9 @@ The CLI reads the `TILEBOX_API_KEY` environment variable. Create an API key in t
 export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"
 ```
 
-Use API keys with the smallest permissions needed for the agent's task.
+<Note>
+Alternatively, you can also provide the API key, or override the environment variable with the `--api-key` flag in each command.
+</Note>
 
 ## Discover commands with agent-context
 

diff --git a/api-reference/go/datasets/Collect.mdx b/api-reference/go/datasets/Collect.mdx
@@ -10,12 +10,12 @@ func Collect[K any](seq iter.Seq2[K, error]) ([]K, error)
 
 Convert any sequence into a slice.
 
-It return an error if any of the elements in the sequence has a non-nil error.
+It returns an error if any element in the sequence has a non-nil error.
 
 ## Parameters
 
-<ParamField path="seq" type="iter.Seq2[[]K, error]">
-  The sequence of bytes to convert
+<ParamField path="seq" type="iter.Seq2[K, error]">
+  The sequence to convert.
 </ParamField>
 
 ## Returns

diff --git a/api-reference/go/datasets/Collections.Create.mdx b/api-reference/go/datasets/Collections.Create.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Collections.Create
+title: Collections.Create
 sidebarTitle: Collections.Create
 icon: layer-group
 ---

diff --git a/api-reference/go/datasets/Collections.Delete.mdx b/api-reference/go/datasets/Collections.Delete.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Collections.Delete
+title: Collections.Delete
 sidebarTitle: Collections.Delete
 icon: layer-group
 ---

diff --git a/api-reference/go/datasets/Collections.Get.mdx b/api-reference/go/datasets/Collections.Get.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Collections.Get
+title: Collections.Get
 sidebarTitle: Collections.Get
 icon: layer-group
 ---
@@ -12,7 +12,7 @@ func (collectionClient) Get(
 ) (*datasets.Collection, error)
 ```
 
-Get a dataset by its slug.
+Get a collection by name from a dataset.
 
 ## Parameters
 
@@ -25,7 +25,7 @@ Get a dataset by its slug.
 
 ## Returns
 
-The created collection object.
+A collection object.
 
 <RequestExample>
 ```go Go

diff --git a/api-reference/go/datasets/Collections.GetOrCreate.mdx b/api-reference/go/datasets/Collections.GetOrCreate.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Collections.GetOrCreate
+title: Collections.GetOrCreate
 sidebarTitle: Collections.GetOrCreate
 icon: layer-group
 ---

diff --git a/api-reference/go/datasets/Collections.List.mdx b/api-reference/go/datasets/Collections.List.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Collections.List
+title: Collections.List
 sidebarTitle: Collections.List
 icon: layer-group
 ---

diff --git a/api-reference/go/datasets/Create.mdx b/api-reference/go/datasets/Create.mdx
@@ -0,0 +1,73 @@
+---
+title: Datasets.Create
+sidebarTitle: Create
+icon: laptop-code
+---
+
+```go
+func (datasetClient) Create(
+    ctx context.Context,
+    kind datasets.DatasetKind,
+    codeName string,
+    name string,
+    fields []datasets.Field,
+    options ...datasets.DatasetOption,
+) (*datasets.Dataset, error)
+```
+
+Create a dataset with the given code name, display name, schema kind, and custom fields.
+
+## Parameters
+
+<ParamField path="kind" type="datasets.DatasetKind" required>
+  The dataset kind.
+</ParamField>
+<ParamField path="codeName" type="string" required>
+  The stable code identifier for the dataset.
+</ParamField>
+<ParamField path="name" type="string" required>
+  The display name of the dataset.
+</ParamField>
+<ParamField path="fields" type="[]datasets.Field" required>
+  The custom fields in the dataset schema.
+</ParamField>
+<ParamField path="options" type="[]datasets.DatasetOption">
+  Options for dataset metadata.
+</ParamField>
+
+## Options
+
+<ParamField path="datasets.WithSummary(summary string)">
+  Set a short dataset summary.
+</ParamField>
+<ParamField path="datasets.WithDescription(description string)">
+  Set the dataset's markdown description.
+</ParamField>
+
+## Dataset kinds
+
+<ParamField path="datasets.KindTemporal" type="datasets.DatasetKind">
+  A dataset that contains timestamp, ID, and ingestion time fields.
+</ParamField>
+<ParamField path="datasets.KindSpatiotemporal" type="datasets.DatasetKind">
+  A dataset that contains timestamp, ID, ingestion time, and geometry fields.
+</ParamField>
+
+## Returns
+
+The created dataset object.
+
+<RequestExample>
+```go Go
+dataset, err := client.Datasets.Create(ctx,
+    datasets.KindSpatiotemporal,
+    "my_catalog",
+    "My catalog",
+    []datasets.Field{
+        field.String("source").Description("Source system"),
+        field.Float64("cloud_cover"),
+    },
+    datasets.WithSummary("Scenes prepared for analysis"),
+)
+```
+</RequestExample>
diff --git a/api-reference/go/datasets/CreateOrUpdate.mdx b/api-reference/go/datasets/CreateOrUpdate.mdx
@@ -1,43 +1,58 @@
 ---
-title: Client.Datasets.Create
-sidebarTitle: Create
+title: Datasets.CreateOrUpdate
+sidebarTitle: CreateOrUpdate
 icon: laptop-code
 ---
 
 ```go
 func (datasetClient) CreateOrUpdate(
     ctx context.Context,
     kind datasets.DatasetKind,
-    codeName string, 
+    codeName string,
     name string,
-    fields []Field,
+    fields []datasets.Field,
+    options ...datasets.DatasetOption,
 ) (*datasets.Dataset, error)
 ```
 
-Create a dataset or update an existing one, if a dataset with the given `codeName` already exists.
+Create a dataset or update an existing dataset if a dataset with the given `codeName` already exists.
+
+If the dataset already exists, Tilebox applies the same schema update rules as a direct update. New fields can be added to non-empty datasets. Breaking schema changes are only allowed for empty datasets.
 
 ## Parameters
 
-<ParamField path="kind" type="datasets.DatasetKind">
-  The kind of the dataset
+<ParamField path="kind" type="datasets.DatasetKind" required>
+  The dataset kind.
+</ParamField>
+<ParamField path="codeName" type="string" required>
+  The stable code identifier for the dataset.
+</ParamField>
+<ParamField path="name" type="string" required>
+  The display name of the dataset.
 </ParamField>
-<ParamField path="codeName" type="string">
-  The code name of the dataset
+<ParamField path="fields" type="[]datasets.Field" required>
+  The custom fields in the dataset schema.
 </ParamField>
-<ParamField path="name" type="string">
-  The name of the dataset
+<ParamField path="options" type="[]datasets.DatasetOption">
+  Options for dataset metadata.
+</ParamField>
+
+## Options
+
+<ParamField path="datasets.WithSummary(summary string)">
+  Set a short dataset summary.
 </ParamField>
-<ParamField path="fields" type="[]Field">
-  The fields of the dataset
+<ParamField path="datasets.WithDescription(description string)">
+  Set the dataset's markdown description.
 </ParamField>
 
 ## Dataset kinds
 
 <ParamField path="KindTemporal" type="datasets.DatasetKind">
-  A dataset that contains a timestamp field
+  A dataset that contains timestamp, ID, and ingestion time fields.
 </ParamField>
 <ParamField path="KindSpatiotemporal" type="datasets.DatasetKind">
-  A dataset that contains a timestamp field and a geometry field
+  A dataset that contains timestamp, ID, ingestion time, and geometry fields.
 </ParamField>
 
 ## Field types
@@ -87,19 +102,20 @@ Create a dataset or update an existing one, if a dataset with the given `codeNam
 
 ## Returns
 
-The created dataset object.
+The created or updated dataset object.
 
 <RequestExample>
 ```go Go
 dataset, err := client.Datasets.CreateOrUpdate(ctx,
     datasets.KindSpatiotemporal,
     "my_catalog",
-    "My personal catalog",
-    []Field{
+    "My catalog",
+    []datasets.Field{
         field.String("field1"),
         field.Int64("field2").Repeated(),
         field.Geometry("field3").Description("Field 3").ExampleValue("Value 3"),
     },
+    datasets.WithSummary("Scenes prepared for analysis"),
 )
 ```
 </RequestExample>
diff --git a/api-reference/go/datasets/DatapointDecoder.Unmarshal.mdx b/api-reference/go/datasets/DatapointDecoder.Unmarshal.mdx
@@ -0,0 +1,55 @@
+---
+title: DatapointDecoder.Unmarshal
+sidebarTitle: DatapointDecoder.Unmarshal
+icon: layer-group
+---
+
+```go
+func (d datasets.DatapointDecoder) Unmarshal(
+    descriptor *datasets.DatapointDescriptor,
+    data []byte,
+) (map[string]any, error)
+```
+
+Decode a raw protobuf datapoint into a JSON-like map with configurable protobuf decoding options.
+
+## Parameters
+
+<ParamField path="descriptor" type="*datasets.DatapointDescriptor" required>
+  The descriptor returned by [`NewDatapointDescriptor`](/api-reference/go/datasets/NewDatapointDescriptor).
+</ParamField>
+<ParamField path="data" type="[]byte" required>
+  The raw protobuf datapoint bytes returned by a datapoint query.
+</ParamField>
+
+## Decoder options
+
+<ParamField path="AllowPartial" type="bool">
+  Allow messages that are missing required fields.
+</ParamField>
+<ParamField path="DiscardUnknown" type="bool">
+  Ignore unknown fields in the raw protobuf message.
+</ParamField>
+<ParamField path="Resolver">
+  Override the resolver used to look up message and extension types.
+</ParamField>
+<ParamField path="RecursionLimit" type="int">
+  Limit how deeply nested messages may be decoded. A zero value uses the protobuf default.
+</ParamField>
+
+## Returns
+
+A map of datapoint fields, or an error if the raw datapoint cannot be decoded.
+
+<RequestExample>
+```go Go
+decoder := datasets.DatapointDecoder{
+    DiscardUnknown: true,
+}
+
+datapoint, err := decoder.Unmarshal(descriptor, data)
+if err != nil {
+    return err
+}
+```
+</RequestExample>
diff --git a/api-reference/go/datasets/Datapoints.Delete.mdx b/api-reference/go/datasets/Datapoints.Delete.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Datapoints.Delete
+title: Datapoints.Delete
 sidebarTitle: Datapoints.Delete
 icon: layer-group
 ---

diff --git a/api-reference/go/datasets/Datapoints.DeleteIDs.mdx b/api-reference/go/datasets/Datapoints.DeleteIDs.mdx
@@ -1,5 +1,5 @@
 ---
-title: Client.Datapoints.DeleteIDs
+title: Datapoints.DeleteIDs
 sidebarTitle: Datapoints.DeleteIDs
 icon: layer-group
 ---