User guides

AGENTS.md

@@ -21,8 +21,10 @@ Navigation is defined in `docs.json` and currently follows this top-level struct
 When adding or moving pages:
 
 1. Keep `docs.json` in sync with actual files.
-2. Keep pages grouped by product area (`datasets/`, `workflows/`, `storage/`, `sdks/`, `guides/`, `api-reference/`).
-3. Preserve the current pattern where high-level landing pages link to deeper pages via `Card`/`HeroCard` blocks.
+2. Keep page paths aligned with their navigation section. If a page appears under a named group such as `Agents and AI Tools`, `Run and Inspect`, or `Automations`, place it under the matching slugged folder (`agents-and-ai-tools/`, `workflows/run-and-inspect/`, `workflows/automations/`) so the URL reflects the sidebar structure.
+3. Keep pages grouped by product area (`datasets/`, `workflows/`, `sdks/`, `guides/`, `api-reference/`).
+4. Keep the User Guides nav and the [Tilebox Cookbook](/guides/cookbook) in sync. Whenever you add, remove, rename, or move a `guides/**` page in `docs.json`, update `guides/cookbook.mdx` with the same guide metadata, and vice versa.
+5. Preserve the current pattern where high-level landing pages link to deeper pages via `Card`/`HeroCard` blocks.
 
 ## Diátaxis Mapping
 
@@ -142,10 +144,12 @@ For any substantial docs update, verify all of the following:
 
 1. Page intent matches a single Diátaxis category.
 2. Page is linked in `docs.json` in the correct section.
-3. Internal links resolve and `mintlify broken-links` passes.
-4. Vale warnings/errors are addressed or intentionally accepted.
-5. New screenshots/assets are optimized and use correct paths.
-6. Language and terminology match surrounding Tilebox docs.
+3. The page path, `docs.json` entry, and expected public URL match the navigation group slug.
+4. If the page is under `guides/**`, the User Guides nav and `guides/cookbook.mdx` are both updated.
+5. Internal links resolve and `mintlify broken-links` passes.
+6. Vale warnings/errors are addressed or intentionally accepted.
+7. New screenshots/assets are optimized and use correct paths.
+8. Language and terminology match surrounding Tilebox docs.
 
 ## Notes On API Reference Pages
 

agentic-development/agent-skills.mdx → agents-and-ai-tools/agent-skills.mdx

@@ -45,4 +45,4 @@ 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.
+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.

agentic-development/ai-interfaces.mdx → agents-and-ai-tools/ai-interfaces.mdx

@@ -10,9 +10,9 @@ Tilebox gives agents multiple ways to get context and take action. The right int
 
 | Interface | Use it for | What it gives the agent |
 | --- | --- | --- |
-| [Tilebox CLI](/agentic-development/tilebox-cli) | Default setup for coding agents, terminal operations, automation, and CI-friendly workflows | Structured command output, command discovery, and predictable inputs |
-| [Agent Skills](/agentic-development/agent-skills) | Repeated Tilebox tasks across datasets, jobs, and automations | Instructions for composing CLI commands into end-to-end workflows |
-| [Tilebox MCP](/agentic-development/tilebox-mcp) | Web-based agents, chat tools, or MCP-capable clients where terminal access is limited | Authenticated tools for datasets, workflows, and documentation search |
+| [Tilebox CLI](/agents-and-ai-tools/tilebox-cli) | Default setup for coding agents, terminal operations, automation, and CI-friendly workflows | Structured command output, command discovery, and predictable inputs |
+| [Agent Skills](/agents-and-ai-tools/agent-skills) | Repeated Tilebox tasks across datasets, jobs, and automations | Instructions for composing CLI commands into end-to-end workflows |
+| [Tilebox MCP](/agents-and-ai-tools/tilebox-mcp) | Web-based agents, chat tools, or MCP-capable clients where terminal access is limited | Authenticated tools for datasets, workflows, and documentation search |
 | [Tilebox SDKs](/sdks/introduction) | Application code and production integrations | Language-native APIs for Python and Go |
 | [`llms-full.txt`](https://docs.tilebox.com/llms-full.txt) | Documentation-only context | A static markdown bundle of the Tilebox documentation |
 

agentic-development/overview.mdx → agents-and-ai-tools/overview.mdx

@@ -1,10 +1,10 @@
 ---
-title: AI Overview
-description: Learn how Tilebox supports agentic development through the CLI, agent skills, the MCP server, and documentation context.
+title: Agents and AI tools
+description: Learn how Tilebox gives coding agents access to the same data, workflow, job, and observability tools that developers use.
 icon: brain-circuit
 ---
 
-AI-assisted development in Tilebox is built around giving agents the same operational context that developers use: current documentation, authenticated access to Tilebox resources, and predictable tools for running actions. The section explains how to connect agents to Tilebox, which interface to use for each task, and how the Tilebox CLI and skills help agents work with datasets and workflows.
+Tilebox gives agents the same operational context that developers use: current documentation, authenticated access to Tilebox resources, and predictable tools for running actions. This section explains how to connect agents to Tilebox, which interface to use for each task, and how the Tilebox CLI and skills help agents work with datasets and workflows.
 
 ## How Tilebox supports agents
 
@@ -14,18 +14,18 @@ Tilebox supports agents through a CLI-based setup. The CLI gives agents a determ
   <Card title="Onboard your agent" icon="rocket" href="/onboard-your-agent">
     Configure an agent with the Tilebox CLI, Tilebox skills, and documentation context.
   </Card>
-  <Card title="AI interfaces" icon="route" href="/agentic-development/ai-interfaces">
+  <Card title="AI interfaces" icon="route" href="/agents-and-ai-tools/ai-interfaces">
     Decide when to use MCP, the CLI, skills, SDKs, or documentation context.
   </Card>
-  <Card title="Tilebox MCP" icon="plug" href="/agentic-development/tilebox-mcp">
-    Connect AI tools to the Tilebox MCP server when terminal access is not available.
-  </Card>
-  <Card title="Tilebox CLI" icon="terminal" href="/agentic-development/tilebox-cli">
+  <Card title="Tilebox CLI" icon="terminal" href="/agents-and-ai-tools/tilebox-cli">
     Install the CLI, authenticate it, and use agent-friendly command patterns.
   </Card>
-  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/agentic-development/agent-skills">
+  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/agents-and-ai-tools/agent-skills">
     Install Tilebox skills that teach agents how to work with Tilebox tools.
   </Card>
+  <Card title="Tilebox MCP" icon="plug" href="/agents-and-ai-tools/tilebox-mcp">
+    Connect AI tools to the Tilebox MCP server when terminal access is not available.
+  </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>

agentic-development/tilebox-cli.mdx → agents-and-ai-tools/tilebox-cli.mdx

@@ -1,12 +1,12 @@
 ---
 title: Tilebox CLI
-description: Install, authenticate, and use the Tilebox CLI in AI-assisted development workflows.
+description: Install, authenticate, and use the Tilebox CLI for developer workflows, operations, and AI-assisted development.
 icon: terminal
 ---
 
-The Tilebox CLI is a command-line interface for humans, agents, and automation. It helps AI-assisted workflows by exposing Tilebox operations through explicit commands, supporting structured output, and letting agents inspect the command tree before taking action.
+The Tilebox CLI is a command-line interface for developers, operators, agents, and automation. Use it to inspect Tilebox resources, manage datasets and workflows, submit jobs, start release runners, and run operational commands from the shell.
 
-Use the CLI as the default Tilebox interface for coding agents that can run terminal commands. It keeps actions visible in the shell, works with existing development workflows, and pairs with Tilebox skills for multi-step tasks.
+The CLI is also the default Tilebox interface for coding agents that can run terminal commands. It keeps actions visible in the shell, supports structured output, and pairs with Tilebox skills for multi-step tasks.
 
 ## Install the CLI
 
@@ -69,4 +69,4 @@ The Tilebox skills include guidance for using the CLI in agent workflows. Instal
 npx skills add tilebox/skills
 ```
 
-After installing the skills, ask your agent to inspect `tilebox agent-context` and follow the relevant Tilebox skill before running commands that change resources. If your agent cannot use a terminal, configure the [Tilebox MCP server](/agentic-development/tilebox-mcp) instead.
+After installing the skills, ask your agent to inspect `tilebox agent-context` and follow the relevant Tilebox skill before running commands that change resources. If your agent cannot use a terminal, configure the [Tilebox MCP server](/agents-and-ai-tools/tilebox-mcp) instead.

agentic-development/tilebox-mcp.mdx → agents-and-ai-tools/tilebox-mcp.mdx

@@ -6,7 +6,7 @@ icon: plug
 
 The Tilebox MCP server connects AI tools to Tilebox through the Model Context Protocol. It exposes tools for working with Tilebox datasets and workflows, and it includes documentation search so agents can retrieve current Tilebox context before answering questions or taking action.
 
-Use MCP when your agent cannot easily use terminal commands. For coding agents with shell access, the [Tilebox CLI](/agentic-development/tilebox-cli) and [Agent Skills](/agentic-development/agent-skills) are the default setup. MCP is a good fit for web-based agents, chat tools, or hosted AI clients that support MCP but do not run local commands.
+Use MCP when your agent cannot easily use terminal commands. For coding agents with shell access, the [Tilebox CLI](/agents-and-ai-tools/tilebox-cli) and [Agent Skills](/agents-and-ai-tools/agent-skills) are the default setup. MCP is a good fit for web-based agents, chat tools, or hosted AI clients that support MCP but do not run local commands.
 
 ## What the MCP server provides
 

api-reference/go/workflows/WithSpan.mdx

@@ -12,7 +12,7 @@ func WithSpan(
 ) error
 ```
 
-Wrap a function with a [tracing span](/workflows/observability/tracing) using the current runner's tracer.
+Wrap a function with a [tracing span](/workflows/run-and-inspect/tracing) using the current runner's tracer.
 
 Use `WithSpan` inside a task `Execute` method. If the context is not a task execution context, the function runs without creating a span.
 

api-reference/go/workflows/WithSpanResult.mdx

@@ -12,7 +12,7 @@ func WithSpanResult[Result any](
 ) (Result, error)
 ```
 
-Wrap a function with a [tracing span](/workflows/observability/tracing) using the current runner's tracer and return the function result.
+Wrap a function with a [tracing span](/workflows/run-and-inspect/tracing) using the current runner's tracer and return the function result.
 
 Use `WithSpanResult` inside a task `Execute` method. If the context is not a task execution context, the function runs without creating a span.
 

api-reference/go/workflows/WithTaskSpan.mdx

@@ -12,7 +12,7 @@ workflows.WithTaskSpan(
 ) error
 ```
 
-Wrap a function with a [tracing span](/workflows/observability/tracing) using the current runner's tracer.
+Wrap a function with a [tracing span](/workflows/run-and-inspect/tracing) using the current runner's tracer.
 
 `WithTaskSpan` is an alias for [`WithSpan`](/api-reference/go/workflows/WithSpan). Use it inside a task `Execute` method. If the context is not a task execution context, the function runs without creating a span.
 

api-reference/go/workflows/WithTaskSpanResult.mdx

@@ -12,7 +12,7 @@ workflows.WithTaskSpanResult[Result any](
 ) (Result, error)
 ```
 
-Wrap a function with a [tracing span](/workflows/observability/tracing) using the current runner's tracer and return the function result.
+Wrap a function with a [tracing span](/workflows/run-and-inspect/tracing) using the current runner's tracer and return the function result.
 
 `WithTaskSpanResult` is an alias for [`WithSpanResult`](/api-reference/go/workflows/WithSpanResult). Use it inside a task `Execute` method. If the context is not a task execution context, the function runs without creating a span.
 

api-reference/python/tilebox.datasets/Client.mdx

@@ -9,6 +9,7 @@ class Client(
     url: str = "https://api.tilebox.com",
     token: str | None = None,
     warn_if_unauthenticated: bool = True,
+    transport: Literal["grpc", "http1"] = "grpc",
 )
 ```
 
@@ -28,6 +29,10 @@ Create a Tilebox datasets client.
   Whether to log a warning when no API key is provided for the Tilebox API URL. Defaults to `True`.
 </ParamField>
 
+<ParamField path="transport" type='Literal["grpc", "http1"]'>
+  Network transport to use for API requests. Defaults to `"grpc"`. Use `"http1"` to force the Connect protocol over HTTP/1.1 on networks that do not support gRPC over HTTP/2 correctly.
+</ParamField>
+
 If no API key is provided, the client uses anonymous open data access for public datasets.
 
 <RequestExample>
@@ -42,5 +47,8 @@ client = Client(
     url="https://api.tilebox.com",
     token="YOUR_TILEBOX_API_KEY",
 )
+
+# use HTTP/1.1 if your network blocks or breaks gRPC over HTTP/2
+client = Client(transport="http1")
 ```
 </RequestExample>

api-reference/python/tilebox.workflows/Client.mdx

@@ -10,6 +10,7 @@ class Client(
     token: str | None = None,
     name: str | None = None,
     client_id: UUID | None = None,
+    transport: Literal["grpc", "http1"] = "grpc",
 )
 ```
 
@@ -33,6 +34,10 @@ Create a Tilebox workflows client.
   Optional stable ID used to scope internal loggers. If not set, a random ID is generated.
 </ParamField>
 
+<ParamField path="transport" type='Literal["grpc", "http1"]'>
+  Network transport to use for API requests. Defaults to `"grpc"`. Use `"http1"` to force the Connect protocol over HTTP/1.1 on networks that do not support gRPC over HTTP/2 correctly.
+</ParamField>
+
 ## Sub clients
 
 The workflows client exposes sub clients for interacting with different parts of the Tilebox workflows API.
@@ -88,6 +93,9 @@ client = Client(
     name="sentinel-2-runner",
 )
 
+# use HTTP/1.1 if your network blocks or breaks gRPC over HTTP/2
+client = Client(transport="http1")
+
 # access sub clients
 job_client = client.jobs()
 cluster_client = client.clusters()

api-reference/python/tilebox.workflows/Client.runner.mdx

@@ -29,7 +29,7 @@ For new Python workflow projects, define a reusable [`Runner`](/api-reference/py
 </ParamField>
 
 <ParamField path="cache" type="JobCache">
-  An optional [job cache](/workflows/caches) for caching results from tasks and sharing data between tasks.
+  An optional [job cache](/workflows/run-and-inspect/caches) for caching results from tasks and sharing data between tasks.
 </ParamField>
 
 <ParamField path="context" type="type[RunnerContext] | None">

api-reference/python/tilebox.workflows/JobCache.group.mdx

@@ -7,7 +7,7 @@ icon: box-archive
 def JobCache.group(name: str) -> JobCache
 ```
 
-You can nest caches in a hierarchical manner using [groups](/workflows/caches#groups-and-hierarchical-keys).
+You can nest caches in a hierarchical manner using [groups](/workflows/run-and-inspect/caches#groups-and-hierarchical-keys).
 Groups are separated by a forward slash (/) in the key. This hierarchical structure functions similarly to a file system.
 
 ## Parameters

api-reference/python/tilebox.workflows/Runner.mdx

@@ -23,7 +23,7 @@ A `Runner` object is a reusable definition. Use it for direct execution by conne
 </ParamField>
 
 <ParamField path="cache" type="JobCache | None">
-  Optional [job cache](/workflows/caches) used by tasks executed by this runner.
+  Optional [job cache](/workflows/run-and-inspect/caches) used by tasks executed by this runner.
 </ParamField>
 
 <ParamField path="context" type="type[RunnerContext] | None">

authentication.mdx

@@ -12,26 +12,57 @@ To create an API key, log into the [Tilebox Console](https://console.tilebox.com
 Keep your API keys secure. Deactivate any keys if you suspect they have been compromised.
 </Info>
 
-## Bearer token authentication
+<Frame>
+	<img src="/assets/console/api-keys-light.png" alt="Tilebox Console" className="dark:hidden"  />
+	<img src="/assets/console/api-keys-dark.png" alt="Tilebox Console" className="hidden dark:block" />
+</Frame>
 
-The Tilebox API uses bearer tokens for authentication. You need to pass your API key as the `token` parameter when creating an instance of the client.
+## Set up environment variable
+
+Set `TILEBOX_API_KEY` in your shell environment (optional but recommended). That way, the [Tilebox CLI](/agents-and-ai-tools/tilebox-cli) and SDK clients automatically pick it up.
+
+The following commands persist the variable for future terminal sessions and also make it available in the current session.
+
+<CodeGroup>
+```bash Bash
+echo 'export TILEBOX_API_KEY="<tbx-api-...>"' >> ~/.bashrc
+source ~/.bashrc
+```
+```zsh Zsh
+echo 'export TILEBOX_API_KEY="<tbx-api-...>"' >> ~/.zshrc
+source ~/.zshrc
+```
+```fish Fish
+set -Ux TILEBOX_API_KEY "<tbx-api-...>"
+```
+```powershell PowerShell
+[Environment]::SetEnvironmentVariable("TILEBOX_API_KEY", "<tbx-api-...>", "User")
+$env:TILEBOX_API_KEY = "<tbx-api-...>"
+```
+</CodeGroup>
+
+Open a new terminal after setting the variable to confirm your shell loads it automatically.
+
+## Manual SDK authentication
+
+In case you didn't configure your shell environment, you can also pass your API key as the `token` parameter when creating an instance of the SDK clients.
 
 <CodeGroup>
 ```python Python
 from tilebox.datasets import Client as DatasetsClient
 from tilebox.workflows import Client as WorkflowsClient
 
-datasets_client = DatasetsClient(token="YOUR_TILEBOX_API_KEY")
-workflows_client = WorkflowsClient(token="YOUR_TILEBOX_API_KEY")
+datasets_client = DatasetsClient(token="<tbx-api-...>")
+workflows_client = WorkflowsClient(token="<tbx-api-...>")
 ```
 ```go Go
 import (
 	"github.com/tilebox/tilebox-go/datasets/v1"
 	"github.com/tilebox/tilebox-go/workflows/v1"
 )
 
-datasetsClient := datasets.NewClient(datasets.WithAPIKey("YOUR_TILEBOX_API_KEY"))
-workflowsClient := workflows.NewClient(workflows.WithAPIKey("YOUR_TILEBOX_API_KEY"))
+datasetsClient := datasets.NewClient(datasets.WithAPIKey("<tbx-api-...>"))
+workflowsClient := workflows.NewClient(workflows.WithAPIKey("<tbx-api-...>"))
 ```
 </CodeGroup>