From 9942ef98c6394bc1efee0d41756a13c23aa91640 Mon Sep 17 00:00:00 2001 From: Lukas Bindreiter Date: Tue, 23 Jun 2026 14:05:44 +0200 Subject: [PATCH 1/3] Fix vale lint issues --- .github/styles/config/vocabularies/docs/accept.txt | 3 +++ .github/workflows/lint.yml | 6 +++--- .vale.ini | 2 ++ AGENTS.md | 7 +++++++ agent-onboarding.mdx | 8 ++++---- workflows/concepts/runners.mdx | 14 +++++++------- 6 files changed, 26 insertions(+), 14 deletions(-) diff --git a/.github/styles/config/vocabularies/docs/accept.txt b/.github/styles/config/vocabularies/docs/accept.txt index 1a5c282..5b949f3 100644 --- a/.github/styles/config/vocabularies/docs/accept.txt +++ b/.github/styles/config/vocabularies/docs/accept.txt @@ -70,3 +70,6 @@ reprojected (?i)geospatial (?i)cartesian (?i)OAuth +(?i)zsh +(?i)undeploy +(?i)subcommand diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 01bbf16..dc62b76 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -11,7 +11,7 @@ jobs: lfs: true - name: Install Vale run: | - curl -L "https://github.com/errata-ai/vale/releases/download/v3.13.1/vale_3.13.1_Linux_64-bit.tar.gz" -o vale.tar.gz + curl -L "https://github.com/errata-ai/vale/releases/download/v3.15.1/vale_3.15.1_Linux_64-bit.tar.gz" -o vale.tar.gz tar -xzf vale.tar.gz -C /usr/local/bin vale - name: Setup Node uses: actions/setup-node@v6 @@ -33,6 +33,6 @@ jobs: with: node-version: 24 - name: Install Mintlify CLI - run: npm install -g mintlify + run: npm install -g mint - name: Run Mintlify broken-links - run: mintlify broken-links + run: mint broken-links diff --git a/.vale.ini b/.vale.ini index 8c05a33..36ecd53 100644 --- a/.vale.ini +++ b/.vale.ini @@ -8,6 +8,8 @@ MinAlertLevel = warning [*.mdx] BasedOnStyles = Vale, Google, write-good, docs +TokenIgnores = \bCLI\b +BlockIgnores = (?s).*?tilebox-cli-window.*? write-good.TooWordy = NO # we have our own list of too wordy as docs.TooWordy write-good.Passive = NO diff --git a/AGENTS.md b/AGENTS.md index 350448c..5721640 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,6 +126,13 @@ CI notes: 2. CI installs `mdx2vast` before running Vale. 3. CI runs `vale sync && vale .` and `mintlify broken-links`. +Vale expectations: + +1. Run `vale .` after documentation changes and make sure it passes. +2. When writing original content, follow the active Vale rules from the start, including rules for concise language. +3. If the user provides exact copy and it fails Vale, do not rewrite it without approval. Show the issue and ask whether to edit the copy or add an exception. +4. If a larger rewrite is needed to satisfy Vale, or a new or updated rule creates many alerts at once, stop and ask how to proceed. + ## Documentation Graphics And Workflow DAG Assets 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. diff --git a/agent-onboarding.mdx b/agent-onboarding.mdx index 6a3b6db..4449e83 100644 --- a/agent-onboarding.mdx +++ b/agent-onboarding.mdx @@ -1,8 +1,8 @@ # Onboard an agent to Tilebox -You are setting up Tilebox for a coding agent. This is for agents that can run terminal commands and edit code: Amp, Codex, Claude Code, Cursor, or similar. +You are setting up Tilebox for a coding agent that can run terminal commands and edit code, such as Amp, Codex, Claude Code, or Cursor. -If you are running in ChatGPT instead of Codex, or in claude.ai instead of Claude Code, stop and tell the user to switch to the coding version. Do not suggest MCP. +If you are using ChatGPT or claude.ai, stop. Tell the user to switch to Codex or Claude Code. Do not suggest MCP. ## Goal @@ -12,7 +12,7 @@ Get the agent ready to use Tilebox from the terminal: 2. Install the Tilebox skills. 3. Help the user create an API key. 4. Give the user the exact shell command to set `TILEBOX_API_KEY` and reload their current environment. -5. Verify read-only setup. Do not modify Tilebox resources. +5. Verify read-only setup. Do not change Tilebox resources. ## Step 1: install the Tilebox CLI @@ -29,7 +29,7 @@ tilebox --help tilebox agent-context ``` -If `tilebox` is not on `PATH`, use the installed path directly, usually: +If `tilebox` is not on `PATH`, use the default installed path directly: ```bash $HOME/.local/bin/tilebox --help diff --git a/workflows/concepts/runners.mdx b/workflows/concepts/runners.mdx index a8772b6..4e5855e 100644 --- a/workflows/concepts/runners.mdx +++ b/workflows/concepts/runners.mdx @@ -40,7 +40,7 @@ A release runner runs Python workflow releases deployed to a cluster. Start it w tilebox runner start --cluster dev-cluster ``` -The release runner can run releases from multiple workflows at the same time, however only one release per workflow. It continously polls the selected cluster for deployment updates, downloads missing release artifacts, validates and starts python processes for each workflow release, and requests work for all the task identifiers from it's deployed releases. When a new release is deployed or removed, the runner updates the task set it can execute. +The release runner can run releases from multiple workflows at the same time, but only one release per workflow. It continuously polls the selected cluster for deployment updates, downloads missing release artifacts, checks them, starts Python processes for each workflow release, and requests work for every task identifier from its deployed releases. When a new release is deployed or removed, the runner updates the task set it can execute. Release runners currently only support Python workflow projects. The Tilebox CLI invokes the Python runner environment from the published release artifact using `uv`. @@ -48,7 +48,7 @@ The release runner can run releases from multiple workflows at the same time, ho ### Direct runners -A direct runner connects to the Tilebox API from your own code. It is useful when you want full control over the process, deployment environment, dependencies, startup behavior, and scaling. You are responsible for deploying the script or binary, keeping it running, rolling out code changes, and rolling back when needed. +A direct runner connects to the Tilebox API from your own code. Use it when you want full control over the process, deployment environment, dependencies, startup behavior, and scaling. You are responsible for deploying the script or binary, keeping it running, rolling out code changes, and rolling back when needed. Define a `Runner` instance once and connect it to a `Client` during startup. @@ -97,21 +97,21 @@ func main() { ## Task selection -For a runner to pick up a submitted task, all of these conditions must match: +For a runner to pick up a submitted task, these conditions must match: 1. The task was submitted to the same [cluster](/workflows/concepts/clusters) as the runner. 2. The runner advertises a [task identifier with the same name](/workflows/concepts/tasks#task-identifiers) and a [compatible version](/workflows/concepts/tasks#semantic-versioning). -3. The task must be in `QUEUED` [state](/workflows/concepts/tasks#task-states), its [dependencies](/workflows/concepts/tasks#dependencies) are met and it's [maximum retries](/workflows/concepts/tasks#retry-handling) aren't exhausted. +3. The task must be in `QUEUED` [state](/workflows/concepts/tasks#task-states), its [dependencies](/workflows/concepts/tasks#dependencies) are met, and its [maximum retries](/workflows/concepts/tasks#retry-handling) aren't exhausted. Release runners advertise the task identifiers from workflow releases currently deployed to the cluster. Direct runners advertise the task identifiers they register in the running process. - If multiple tasks match those conditions, Tilebox picks one and assigns it to a runner. The remaining tasks stay queued until another matching runner is available. Parallel runner processes can speed up the job execution in such cases. + If multiple tasks match those conditions, Tilebox picks one and assigns it to a runner. The remaining tasks stay queued until another matching runner is available. Parallel runner processes can speed up the job execution in such cases. ## Parallelism -Start multiple runner processes to execute tasks in parallel. Each runner process claims and executes tasks independently. You can run several release runners, several direct runners, or a mix of both in the same cluster. This allows for high parallelism and can be used to scale the execution of tasks to handle large workloads. +Start multiple runner processes to execute tasks in parallel. Each runner process claims and executes tasks independently. You can run multiple release runners, multiple direct runners, or a mix of both in the same cluster. This increases parallelism and helps handle large workloads. To test this, run multiple instances of the runner script in different terminal windows on your local machine, or use the [CLI](/agents-and-ai-tools/tilebox-cli) built-in `parallel` subcommand to start multiple runners in parallel. @@ -125,7 +125,7 @@ To test this, run multiple instances of the runner script in different terminal ## Scaling -One key benefit of this runner architecture is the **ability to scale even while workflows are executing**. You can start new runners at any time, and they can immediately pick up queued tasks to execute. It's not necessary to have an entire processing cluster available at the start of a workflow, as additional runners can be started and stopped as needed. +One key benefit of this runner architecture is the **ability to scale even while workflows are executing**. You can start new runners at any time, and they can immediately pick up queued tasks to execute. You do not need an entire processing cluster available at the start of a workflow, because you can start and stop more runners as needed. This is particularly beneficial in cloud environments, where runners can be automatically started and stopped based on current workload, measured by metrics such as CPU usage. Here's an example scenario: From 4b61e214fb75049efb4f288254ceaf1fa66cea9a Mon Sep 17 00:00:00 2001 From: Lukas Bindreiter Date: Tue, 23 Jun 2026 14:45:01 +0200 Subject: [PATCH 2/3] Add workflow init docs --- agents-and-ai-tools/agent-skills.mdx | 4 +- agents-and-ai-tools/tilebox-cli.mdx | 10 ++ guides/cookbook.mdx | 2 +- .../workflows/agentic-workflow-iteration.mdx | 8 +- .../workflows/build-and-deploy-workflow.mdx | 91 +++++++++++-------- .../build-and-deploy/project-structure.mdx | 18 +++- workflows/build-and-deploy/releases.mdx | 4 +- .../workflow-configuration.mdx | 4 + workflows/concepts/workflow-releases.mdx | 2 + 9 files changed, 97 insertions(+), 46 deletions(-) diff --git a/agents-and-ai-tools/agent-skills.mdx b/agents-and-ai-tools/agent-skills.mdx index 8193d87..7f6a0b1 100644 --- a/agents-and-ai-tools/agent-skills.mdx +++ b/agents-and-ai-tools/agent-skills.mdx @@ -33,7 +33,7 @@ Tilebox skills cover common agent workflows around the CLI, datasets, workflows, | `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 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 | +| `releasing-tilebox-workflows` | Initializing workflow projects, configuring `tilebox.workflow.toml`, building releases, publishing releases, deploying to clusters, and running release runners | ## How to use skills with agents @@ -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`. For a new project, the typical loop starts with `tilebox workflow init`. After that, the agent edits tasks, builds a release, publishes it, deploys it to a development cluster, runs `tilebox runner start`, submits a test job, and inspects logs or spans before iterating. diff --git a/agents-and-ai-tools/tilebox-cli.mdx b/agents-and-ai-tools/tilebox-cli.mdx index 161244d..839d1e5 100644 --- a/agents-and-ai-tools/tilebox-cli.mdx +++ b/agents-and-ai-tools/tilebox-cli.mdx @@ -46,6 +46,16 @@ Use `--json` when the agent needs to parse command output. Structured output is tilebox dataset list --json ``` +## Scaffold workflow projects + +Use the CLI to create a Tilebox workflow and scaffold a Python release project. + +```bash +tilebox workflow init --name "Scene QA" --json +``` + +The command creates the remote workflow, writes `tilebox.workflow.toml`, creates Python project files, adds the `tilebox` dependency, and runs `uv sync`. See [Project Structure](/workflows/build-and-deploy/project-structure) for the generated files and release project layout. + ## Use files and standard input for generated input For larger inputs, prefer file-based flags instead of long shell-quoted strings. The CLI supports input patterns such as `--schema-file`, `--input-file`, `--spatial-extent-file`, and `--description-file`. Many file flags also support `-` for reading from standard input. diff --git a/guides/cookbook.mdx b/guides/cookbook.mdx index dd085ee..5190baa 100644 --- a/guides/cookbook.mdx +++ b/guides/cookbook.mdx @@ -92,7 +92,7 @@ export const cookbookSections = [ { title: "Build and deploy a workflow project", href: "/guides/workflows/build-and-deploy-workflow", - description: "Package a Python workflow release and deploy it to a development cluster.", + description: "Initialize a Python workflow project, publish a release, and deploy it to a development cluster.", icon: "rocket", level: "Beginner", time: "15 min", diff --git a/guides/workflows/agentic-workflow-iteration.mdx b/guides/workflows/agentic-workflow-iteration.mdx index ca4027d..beec80d 100644 --- a/guides/workflows/agentic-workflow-iteration.mdx +++ b/guides/workflows/agentic-workflow-iteration.mdx @@ -26,7 +26,13 @@ Load the Tilebox workflow skills. Inspect `tilebox agent-context workflow --outp ## Create or update the workflow project -Ask the agent to keep the workflow project centered on one reusable `Runner` definition. +For a new workflow project, ask the agent to initialize the project before editing task code. + +```text Prompt +Inspect `tilebox agent-context workflow init --output-schema`. Then initialize a new Tilebox workflow project with `tilebox workflow init --name "" --json`. After initialization, update the generated runner.py with the workflow tasks. +``` + +For an existing workflow project, ask the agent to keep the project centered on one reusable `Runner` definition. ```text Prompt Update this Python workflow project. Keep task classes in `src//tasks.py`, export `runner = Runner(tasks=[...])` from `src//runner.py`, and keep `tilebox.workflow.toml` pointing at that runner object. diff --git a/guides/workflows/build-and-deploy-workflow.mdx b/guides/workflows/build-and-deploy-workflow.mdx index 8a4c76a..3943f60 100644 --- a/guides/workflows/build-and-deploy-workflow.mdx +++ b/guides/workflows/build-and-deploy-workflow.mdx @@ -1,6 +1,6 @@ --- title: Build and deploy a workflow project -description: Structure a Python workflow project, publish a workflow release, and deploy it to a development cluster. +description: Initialize a Python workflow project, publish a workflow release, and deploy it to a development cluster. icon: rocket --- @@ -12,79 +12,91 @@ This guide summarizes the build and deploy path. For the underlying model, see [ - You have installed the [Tilebox CLI](/agents-and-ai-tools/tilebox-cli). - `TILEBOX_API_KEY` is set in the shell where you run commands. -- You have a Python workflow project with a `Runner` object. +- `uv` is installed and available on `PATH`. -## Create the project structure +## Initialize the project -Use a small, importable project layout. +Create a project directory and initialize it as a Tilebox workflow project. + +```bash +mkdir my-workflow +cd my-workflow +tilebox workflow init --name "My Workflow" +``` + +The init command creates the Tilebox workflow, writes `tilebox.workflow.toml`, creates a minimal Python project with `runner.py`, adds the `tilebox` dependency, and runs `uv sync`. It aborts if `tilebox.workflow.toml`, `pyproject.toml`, `runner.py`, or `uv.lock` already exists in the current directory. - - - - + -## Configure the workflow +## Configure a deployment target + +Create a logical cluster to deploy our workflow release to, enabling [release runners](/workflows/concepts/runners#release-runners). + +```bash +tilebox cluster create "workflow-dev" +``` + +```text Output +Slug workflow-dev-<...> +Name workflow-dev +Deletable true +``` -Point `tilebox.workflow.toml` at the exported runner object and include the files the release runner needs. +Add the returned cluster slug to `tilebox.workflow.toml` so deployment commands can refer to a logical environment instead of repeating cluster slugs. ```toml tilebox.workflow.toml [workflow] -slug = "my-workflow" +slug = "my-workflow-<...>" root = "." -runner = "my_workflow.runner:runner" +runner = "runner:runner" [build] include = [ + "tilebox.workflow.toml", "pyproject.toml", "uv.lock", - "my_workflow/**", + "runner.py", ] -exclude = [ - ".venv/**", - "**/__pycache__/**", - "**/*.pyc", -] -use_gitignore = true [targets.dev] -clusters = ["workflow-dev"] +clusters = ["workflow-dev-<...>"] ``` ## Build and publish the release -Build locally first when you want detailed validation output. +Create a new release of the workflow and publish it to Tilebox. ```bash -tilebox workflow build-release --debug --json +tilebox workflow publish-release ``` -Publish the checked release content. +Publishing creates an immutable release. It does not change what any cluster runs until you deploy it. -```bash -RELEASE_ID=$(tilebox workflow publish-release --json | jq -r '.id') -``` + +Build locally first when you want detailed validation output. -Publishing creates an immutable release. It does not change what any cluster runs until you deploy it. +`tilebox workflow build-release --debug` + ## Deploy to a development cluster Deploy the release to the development target. ```bash -tilebox workflow deploy-release --release "$RELEASE_ID" --target dev --json +tilebox workflow deploy-release --latest --target dev ``` Start a release runner in an environment you control. ```bash -tilebox runner start --cluster workflow-dev --debug +tilebox runner start --cluster workflow-dev-9xK2mQ4pL8nR7s --debug ``` ## Run and inspect a job @@ -92,21 +104,24 @@ tilebox runner start --cluster workflow-dev --debug Submit a task that matches one of the identifiers discovered from the release. ```bash -JOB_ID=$(tilebox job submit \ +tilebox job submit \ --name my-workflow-test \ - --task tilebox.com/example/ProcessScene \ - --version v1.0 \ - --cluster workflow-dev \ - --input '{"scene_id":"S2A_001"}' \ - --wait \ - --json | jq -r '.id') + --task my-workflow-a1b2/HelloWorld \ + --version v0.0 \ + --cluster workflow-dev-9xK2mQ4pL8nR7s \ + --input '{"name":"Tilebox"}' \ + --wait +``` + +```text +Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90 ``` Inspect the result before making the next change. ```bash -tilebox job logs "$JOB_ID" --json -tilebox job spans "$JOB_ID" --json +tilebox job logs +tilebox job spans ``` ## Next steps diff --git a/workflows/build-and-deploy/project-structure.mdx b/workflows/build-and-deploy/project-structure.mdx index 0e13360..d6120ef 100644 --- a/workflows/build-and-deploy/project-structure.mdx +++ b/workflows/build-and-deploy/project-structure.mdx @@ -1,6 +1,6 @@ --- title: Project Structure -description: Structure a Python workflow project so releases can be built reproducibly and release runners can discover and execute its tasks. +description: Initialize and structure a Python workflow project so releases can be built reproducibly and release runners can discover and execute its tasks. icon: folder-tree --- @@ -12,7 +12,21 @@ A Python workflow project contains task classes, a `Runner` definition, and a `t Keep the project small and importable from its root. Release builds import the configured runner object, check that the Python runtime starts, and package the selected files into an immutable artifact. -## Project structure +## Scaffold a workflow project + +For a new Python workflow project, use the CLI to create the Tilebox workflow and scaffold the local files. + +```bash +tilebox workflow init --name "Scene QA" +``` + +The `--name` flag is optional. When omitted, the command derives the local project slug from the current directory name. The command converts the name to a slug, truncates it to at most 40 characters, creates the remote workflow, and writes the API-returned workflow slug to `tilebox.workflow.toml`. + +`tilebox workflow init` creates `tilebox.workflow.toml`, `pyproject.toml`, and `runner.py`, adds the `tilebox` Python dependency, and runs `uv sync` to create the local environment and `uv.lock` file. It requires `uv` on `PATH` and aborts without changing the directory if any of `tilebox.workflow.toml`, `pyproject.toml`, `runner.py`, or `uv.lock` already exists. + +The generated project is intentionally small. Edit `runner.py` directly for prototypes, or move task code into a package as the workflow grows. + +## Manual project structure Use a layout where task code and the runner definition are importable from the project root. diff --git a/workflows/build-and-deploy/releases.mdx b/workflows/build-and-deploy/releases.mdx index 47895a5..c0db673 100644 --- a/workflows/build-and-deploy/releases.mdx +++ b/workflows/build-and-deploy/releases.mdx @@ -12,7 +12,7 @@ The release lifecycle separates code packaging from cluster rollout. Building an | Stage | What it does | What changes | | --- | --- | --- | -| Workflow creation | Creates the long-lived workflow object and slug. | Adds a workflow record. | +| Workflow initialization | Creates the long-lived workflow object and local project configuration. | Adds a workflow record and, when using `tilebox workflow init`, local scaffold files. | | Local build | Resolves files, creates a deterministic artifact, and checks the configured Python runtime. | Writes local build output and cache entries. | | Publishing | Uploads the artifact when needed and creates an immutable release record. | Adds or reuses a workflow release. | | Deployment | Maps a release to one or more clusters. | Changes which release runners can execute the release. | @@ -22,7 +22,7 @@ The release lifecycle separates code packaging from cluster rollout. Building an A workflow is the stable object that releases belong to. It has a slug, such as `my-workflow`, which is referenced from `tilebox.workflow.toml`. The workflow object is not the executable code itself; it provides the long-lived name under which releases are published. -Create the workflow object once, then keep publishing new releases to it as the code changes. This gives release runners and deployment commands a stable workflow identity while each release remains immutable. +Create the workflow object once, then keep publishing new releases to it as the code changes. For new Python workflow projects, `tilebox workflow init` creates the workflow object and writes the returned slug into `tilebox.workflow.toml`. This gives release runners and deployment commands a stable workflow identity while each release remains immutable. ## Release artifact diff --git a/workflows/build-and-deploy/workflow-configuration.mdx b/workflows/build-and-deploy/workflow-configuration.mdx index 40c47af..a93637a 100644 --- a/workflows/build-and-deploy/workflow-configuration.mdx +++ b/workflows/build-and-deploy/workflow-configuration.mdx @@ -8,6 +8,10 @@ icon: file-code The Tilebox command-line tool searches upward from the current directory for the nearest configuration file. This lets release commands run from the project root or from subdirectories inside the project. + + For new projects, run `tilebox workflow init` to create `tilebox.workflow.toml`, `pyproject.toml`, and `runner.py`. Edit the generated configuration when you need package layouts, deployment targets, or custom build includes. + + ## Minimal configuration ```toml diff --git a/workflows/concepts/workflow-releases.mdx b/workflows/concepts/workflow-releases.mdx index a9976b3..cbe8af0 100644 --- a/workflows/concepts/workflow-releases.mdx +++ b/workflows/concepts/workflow-releases.mdx @@ -6,6 +6,8 @@ icon: box-open A workflow is a set of interrelated tasks. You can run those tasks directly without registering the workflow with Tilebox. Registering a workflow with the Tilebox API gives it a stable slug, which lets you publish immutable release artifacts to it and deploy a release to one or more clusters. +For a new Python release project, `tilebox workflow init` creates the workflow object and scaffolds the local project files used to build releases. + That release path enables [release runners](/workflows/concepts/runners#release-runners). Release runners operate on a cluster, pick up all the releases deployed to that cluster, and execute tasks. This provides an easy way of deploying workflows to a compute cluster, including a quick and agent-accessible iteration loop: change code, publish a release, deploy it, run a job, and inspect the result. ## Workflows and releases From 4cec21c409064075919e1c174b6e8aa8a202bb20 Mon Sep 17 00:00:00 2001 From: Lukas Bindreiter Date: Tue, 23 Jun 2026 15:29:31 +0200 Subject: [PATCH 3/3] Simplify guides --- AGENTS.md | 2 + agents-and-ai-tools/agent-skills.mdx | 8 +-- .../configure-storage-event-automations.mdx | 4 +- guides/operations/query-logs-and-spans.mdx | 4 +- .../workflows/agentic-workflow-iteration.mdx | 49 +++++++++-------- .../workflows/build-and-deploy-workflow.mdx | 6 +-- guides/workflows/debug-failed-run.mdx | 8 +-- guides/workflows/deploy-to-your-compute.mdx | 8 +-- .../workflows/execute-tasks-in-parallel.mdx | 4 +- .../retry-with-compatible-release.mdx | 12 ++--- guides/workflows/run-your-first-workflow.mdx | 4 +- index.mdx | 52 +++++++++---------- onboard-your-agent.mdx | 8 +-- snippets/components.mdx | 21 +++++--- style.css | 50 +++++++++++------- 15 files changed, 135 insertions(+), 105 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5721640..17fb9f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,6 +54,8 @@ Common page flow patterns in this repo: 3. Step-by-step sections for procedures. 4. `Next steps` links/cards at the end. +For command examples in user guides, optimize for reader copy/paste rather than fully scripted automation. Prefer direct `tilebox` commands and simple shell setup commands such as `cd`, `mkdir`, and `export`. Avoid Bash command substitution, uppercase helper variables such as `RELEASE_ID` or `JOB_ID`, `jq` pipelines, heredocs, and `--json` unless the page is explicitly about structured output or automation. When a later command needs a value returned by an earlier command, show the earlier command output and use a placeholder such as `` in follow-up commands. + ## Terminology, Capitalization, And Naming Use consistent product language: diff --git a/agents-and-ai-tools/agent-skills.mdx b/agents-and-ai-tools/agent-skills.mdx index 7f6a0b1..81f7023 100644 --- a/agents-and-ai-tools/agent-skills.mdx +++ b/agents-and-ai-tools/agent-skills.mdx @@ -4,6 +4,8 @@ description: Install Tilebox skills that teach AI agents how to work with Tilebo icon: wand-magic-sparkles --- +import { AgentPrompt } from '/snippets/components.mdx'; + Tilebox skills are task-level instructions for AI agents. They explain how to use the Tilebox CLI, which command patterns to prefer, and how to approach common workflows such as dataset management and job monitoring. ## Install Tilebox skills @@ -39,9 +41,9 @@ Tilebox skills cover common agent workflows around the CLI, datasets, workflows, Ask your agent to load the most specific Tilebox skill for the task. For example, use `managing-tilebox-datasets` for schema work and `managing-tilebox-jobs` for workflow execution or observability tasks. -```text Prompt -Load the relevant Tilebox skills. Use the Tilebox CLI to submit a Sentinel-2 mosaic job, then monitor it until it completes. -``` + + Load the relevant Tilebox skills. Use the Tilebox CLI to submit a Sentinel-2 mosaic job, then monitor it until it completes. + 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. diff --git a/guides/operations/configure-storage-event-automations.mdx b/guides/operations/configure-storage-event-automations.mdx index 0994330..8c619fc 100644 --- a/guides/operations/configure-storage-event-automations.mdx +++ b/guides/operations/configure-storage-event-automations.mdx @@ -61,8 +61,8 @@ automations.create_storage_event_automation( Create or change a matching object, then inspect the submitted job in the Console or through the Tilebox command-line tool. ```bash -tilebox job logs --json -tilebox job spans --json +tilebox job logs +tilebox job spans ``` ## Next steps diff --git a/guides/operations/query-logs-and-spans.mdx b/guides/operations/query-logs-and-spans.mdx index 4d24885..2094ed0 100644 --- a/guides/operations/query-logs-and-spans.mdx +++ b/guides/operations/query-logs-and-spans.mdx @@ -15,10 +15,10 @@ tilebox job logs --json tilebox job spans --json ``` -Use `jq` to narrow the output during debugging. +Limit or sort the output during debugging. ```bash -tilebox job logs --json | jq '.[] | select(.level == "ERROR")' +tilebox job logs --limit 10 --sort desc ``` ## Query from Python diff --git a/guides/workflows/agentic-workflow-iteration.mdx b/guides/workflows/agentic-workflow-iteration.mdx index beec80d..e025a09 100644 --- a/guides/workflows/agentic-workflow-iteration.mdx +++ b/guides/workflows/agentic-workflow-iteration.mdx @@ -4,6 +4,8 @@ description: Use a coding agent with the Tilebox command-line tool to edit, publ icon: robot --- +import { AgentPrompt } from '/snippets/components.mdx'; + This guide shows the recommended loop for AI-assisted workflow development. The agent edits Python workflow code, publishes a release, deploys it to a development cluster, starts a release runner, submits a test job, and inspects logs or spans before iterating. Use this loop when you want the code under test to match the artifact that release runners execute. @@ -20,23 +22,23 @@ npx skills add tilebox/skills Ask the agent to inspect the command-line tool before changing resources. -```text Prompt -Load the Tilebox workflow skills. Inspect `tilebox agent-context workflow --output-schema` and `tilebox agent-context runner start --output-schema`. Do not modify Tilebox resources yet. -``` + + Load the Tilebox workflow skills. Inspect `tilebox agent-context workflow --output-schema` and `tilebox agent-context runner start --output-schema`. Do not modify Tilebox resources yet. + ## Create or update the workflow project For a new workflow project, ask the agent to initialize the project before editing task code. -```text Prompt -Inspect `tilebox agent-context workflow init --output-schema`. Then initialize a new Tilebox workflow project with `tilebox workflow init --name "" --json`. After initialization, update the generated runner.py with the workflow tasks. -``` + + Inspect `tilebox agent-context workflow init --output-schema`. Then initialize a new Tilebox workflow project with `tilebox workflow init --name ""`. After initialization, update the generated runner.py with the workflow tasks. + For an existing workflow project, ask the agent to keep the project centered on one reusable `Runner` definition. -```text Prompt -Update this Python workflow project. Keep task classes in `src//tasks.py`, export `runner = Runner(tasks=[...])` from `src//runner.py`, and keep `tilebox.workflow.toml` pointing at that runner object. -``` + + Update this Python workflow project. Keep task classes in `src//tasks.py`, export `runner = Runner(tasks=[...])` from `src//runner.py`, and keep `tilebox.workflow.toml` pointing at that runner object. + The direct runner path and release runner path should use the same `Runner` object. Direct execution uses `runner.connect_to(Client(), cluster=...)`; release execution uses `tilebox.workflow.toml` and `tilebox runner start`. @@ -45,7 +47,7 @@ The direct runner path and release runner path should use the same `Runner` obje Create a development cluster if you do not already have one. ```bash -tilebox cluster create "workflow-dev" --json +tilebox cluster create "workflow-dev" ``` Add the cluster slug to `tilebox.workflow.toml`. @@ -60,21 +62,21 @@ clusters = ["workflow-dev-abc123"] Ask the agent to build locally first when it needs detailed validation output. ```bash -tilebox workflow build-release --debug --json +tilebox workflow build-release --debug ``` Then publish the release. ```bash -RELEASE_ID=$(tilebox workflow publish-release --json | jq -r '.id') +tilebox workflow publish-release ``` ## Deploy to the development cluster -Deploy the exact release the agent just published. +Deploy the latest release the agent just published. ```bash -tilebox workflow deploy-release --release "$RELEASE_ID" --target dev --json +tilebox workflow deploy-release --latest --target dev ``` This updates cluster deployment state. It does not submit a job. @@ -94,21 +96,24 @@ Keep this runner running while the agent iterates. It can run multiple deployed Submit a root task to the same cluster. ```bash -JOB_ID=$(tilebox job submit \ +tilebox job submit \ --name my-workflow-test \ --task tilebox.com/example/ProcessScene \ --version v1.0 \ --cluster workflow-dev-abc123 \ --input '{"scene_id":"S2A_001"}' \ - --wait \ - --json | jq -r '.id') + --wait +``` + +```text +Job submitted: 019ef7a2-56b4-7a86-9c4d-52a1792b1e90 ``` Inspect logs and spans when the job fails or takes longer than expected. ```bash -tilebox job logs "$JOB_ID" --json -tilebox job spans "$JOB_ID" --json +tilebox job logs +tilebox job spans ``` ## Iterate safely @@ -116,9 +121,9 @@ tilebox job spans "$JOB_ID" --json For compatible fixes, keep the task identifier name and major version stable. Publish and deploy the fix, then retry the failed job. ```bash -RELEASE_ID=$(tilebox workflow publish-release --json | jq -r '.id') -tilebox workflow deploy-release --release "$RELEASE_ID" --target dev --json -tilebox job retry "$JOB_ID" --json +tilebox workflow publish-release +tilebox workflow deploy-release --latest --target dev +tilebox job retry ``` For breaking input or behavior changes, bump the task major version and submit a new test job. diff --git a/guides/workflows/build-and-deploy-workflow.mdx b/guides/workflows/build-and-deploy-workflow.mdx index 3943f60..0e794bc 100644 --- a/guides/workflows/build-and-deploy-workflow.mdx +++ b/guides/workflows/build-and-deploy-workflow.mdx @@ -37,7 +37,7 @@ The init command creates the Tilebox workflow, writes `tilebox.workflow.toml`, c ## Configure a deployment target -Create a logical cluster to deploy our workflow release to, enabling [release runners](/workflows/concepts/runners#release-runners). +Create a logical cluster to deploy the workflow release to, enabling [release runners](/workflows/concepts/runners#release-runners). ```bash tilebox cluster create "workflow-dev" @@ -106,8 +106,8 @@ Submit a task that matches one of the identifiers discovered from the release. ```bash tilebox job submit \ --name my-workflow-test \ - --task my-workflow-a1b2/HelloWorld \ - --version v0.0 \ + --task my-workflow/HelloWorld \ + --version v0.1 \ --cluster workflow-dev-9xK2mQ4pL8nR7s \ --input '{"name":"Tilebox"}' \ --wait diff --git a/guides/workflows/debug-failed-run.mdx b/guides/workflows/debug-failed-run.mdx index 15262fa..2328e50 100644 --- a/guides/workflows/debug-failed-run.mdx +++ b/guides/workflows/debug-failed-run.mdx @@ -11,8 +11,8 @@ Use this guide when a workflow job fails, runs slower than expected, or stays qu Open the job in the [Tilebox Console](https://console.tilebox.com/workflows/jobs), or use the Tilebox command-line tool if you already have the job ID. ```bash -tilebox job logs --json -tilebox job spans --json +tilebox job logs +tilebox job spans ``` ## Check task state first @@ -32,7 +32,7 @@ Common checks: Logs show messages emitted by task code and runner context attached by Tilebox. ```bash -tilebox job logs --json | jq '.[] | {time, level, body, attributes}' +tilebox job logs ``` Use structured log fields in your tasks so the relevant scene ID, product ID, path, or model name appears in the log record. @@ -42,7 +42,7 @@ Use structured log fields in your tasks so the relevant scene ID, product ID, pa Traces show task timing, parent-child relationships, custom spans, and failures. ```bash -tilebox job spans --json | jq '.[] | {name, status, duration}' +tilebox job spans ``` Use traces to find slow subtasks, repeated retries, and failures inside a specific custom span. diff --git a/guides/workflows/deploy-to-your-compute.mdx b/guides/workflows/deploy-to-your-compute.mdx index 90fbb03..0c61ecf 100644 --- a/guides/workflows/deploy-to-your-compute.mdx +++ b/guides/workflows/deploy-to-your-compute.mdx @@ -13,8 +13,8 @@ A cluster is the routing boundary for jobs and runners. Jobs submitted to a clus Use separate clusters for environments that should not run the same code by accident, such as development and production-like compute. ```bash -tilebox cluster create "workflow-dev" --json -tilebox cluster create "workflow-prod" --json +tilebox cluster create "workflow-dev" +tilebox cluster create "workflow-prod" ``` ## Deploy a release to the cluster @@ -22,7 +22,7 @@ tilebox cluster create "workflow-prod" --json Deploy a published workflow release to the cluster or to a target defined in `tilebox.workflow.toml`. ```bash -tilebox workflow deploy-release --release "$RELEASE_ID" --cluster workflow-dev --json +tilebox workflow deploy-release --latest --cluster workflow-dev ``` For repeated deployments, define targets in the workflow configuration. @@ -38,7 +38,7 @@ clusters = ["workflow-prod"] Then deploy by target name. ```bash -tilebox workflow deploy-release --release "$RELEASE_ID" --target dev --json +tilebox workflow deploy-release --latest --target dev ``` ## Start release runners where the work should run diff --git a/guides/workflows/execute-tasks-in-parallel.mdx b/guides/workflows/execute-tasks-in-parallel.mdx index 9abfa31..5810515 100644 --- a/guides/workflows/execute-tasks-in-parallel.mdx +++ b/guides/workflows/execute-tasks-in-parallel.mdx @@ -153,8 +153,8 @@ In the Console, you should see: For command-line inspection, query logs or spans for the job: ```bash -tilebox job logs --json -tilebox job spans --json +tilebox job logs +tilebox job spans ``` ## Next steps diff --git a/guides/workflows/retry-with-compatible-release.mdx b/guides/workflows/retry-with-compatible-release.mdx index ff40c3a..670c20c 100644 --- a/guides/workflows/retry-with-compatible-release.mdx +++ b/guides/workflows/retry-with-compatible-release.mdx @@ -23,13 +23,13 @@ Use a new major task version and submit a new job when the input schema or behav After editing the workflow code, publish a new release. ```bash -RELEASE_ID=$(tilebox workflow publish-release --json | jq -r '.id') +tilebox workflow publish-release ``` For validation details, build locally first. ```bash -tilebox workflow build-release --debug --json +tilebox workflow build-release --debug ``` ## Deploy to the same cluster @@ -37,7 +37,7 @@ tilebox workflow build-release --debug --json Deploy the fixed release to the same cluster that received the original job. ```bash -tilebox workflow deploy-release --release "$RELEASE_ID" --cluster workflow-dev --json +tilebox workflow deploy-release --latest --cluster workflow-dev ``` The job cluster, release deployment cluster, and release runner cluster must match. @@ -47,14 +47,14 @@ The job cluster, release deployment cluster, and release runner cluster must mat Retry the failed job. ```bash -tilebox job retry --json +tilebox job retry ``` Then inspect logs and spans to confirm the fixed task completed. ```bash -tilebox job logs --json -tilebox job spans --json +tilebox job logs +tilebox job spans ``` ## Next steps diff --git a/guides/workflows/run-your-first-workflow.mdx b/guides/workflows/run-your-first-workflow.mdx index 82a3ea7..b53b817 100644 --- a/guides/workflows/run-your-first-workflow.mdx +++ b/guides/workflows/run-your-first-workflow.mdx @@ -73,8 +73,8 @@ Open the job in the [Tilebox Console](https://console.tilebox.com/workflows/jobs For scripted inspection, use the jobs client or the Tilebox command-line tool: ```bash -tilebox job logs --json -tilebox job spans --json +tilebox job logs +tilebox job spans ``` ## Next steps diff --git a/index.mdx b/index.mdx index 3e0c6f7..2085fea 100644 --- a/index.mdx +++ b/index.mdx @@ -31,15 +31,15 @@ export const HomeSearch = () => {