Document tilebox workflow init

.github/styles/config/vocabularies/docs/accept.txt

@@ -70,3 +70,6 @@ reprojected
 (?i)geospatial
 (?i)cartesian
 (?i)OAuth
+(?i)zsh
+(?i)undeploy
+(?i)subcommand

.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

.vale.ini

@@ -8,6 +8,8 @@ MinAlertLevel = warning
 
 [*.mdx]
 BasedOnStyles = Vale, Google, write-good, docs
+TokenIgnores = \bCLI\b
+BlockIgnores = (?s)<Tab title="CLI">.*?tilebox-cli-window.*?</Tab>
 
 write-good.TooWordy = NO # we have our own list of too wordy as docs.TooWordy
 write-good.Passive = NO

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 `<JOB_ID>` in follow-up commands.
+
 ## Terminology, Capitalization, And Naming
 
 Use consistent product language:
@@ -126,6 +128,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.

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

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
@@ -33,16 +35,16 @@ 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
 
 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.
-```
+<AgentPrompt>
+  Load the relevant Tilebox skills. Use the Tilebox CLI to submit a Sentinel-2 mosaic job, then monitor it until it completes.
+</AgentPrompt>
 
 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.

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.

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",

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 <job-id> --json
-tilebox job spans <job-id> --json
+tilebox job logs <job-id>
+tilebox job spans <job-id>
 ```
 
 ## Next steps

guides/operations/query-logs-and-spans.mdx

@@ -15,10 +15,10 @@ tilebox job logs <job-id> --json
 tilebox job spans <job-id> --json
 ```
 
-Use `jq` to narrow the output during debugging.
+Limit or sort the output during debugging.
 
 ```bash
-tilebox job logs <job-id> --json | jq '.[] | select(.level == "ERROR")'
+tilebox job logs <job-id> --limit 10 --sort desc
 ```
 
 ## Query from Python

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,17 +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.
-```
+<AgentPrompt>
+  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.
+</AgentPrompt>
 
 ## 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
-Update this Python workflow project. Keep task classes in `src/<package>/tasks.py`, export `runner = Runner(tasks=[...])` from `src/<package>/runner.py`, and keep `tilebox.workflow.toml` pointing at that runner object.
-```
+<AgentPrompt>
+  Inspect `tilebox agent-context workflow init --output-schema`. Then initialize a new Tilebox workflow project with `tilebox workflow init --name "<workflow-name>"`. After initialization, update the generated runner.py with the workflow tasks.
+</AgentPrompt>
+
+For an existing workflow project, ask the agent to keep the project centered on one reusable `Runner` definition.
+
+<AgentPrompt>
+  Update this Python workflow project. Keep task classes in `src/<package>/tasks.py`, export `runner = Runner(tasks=[...])` from `src/<package>/runner.py`, and keep `tilebox.workflow.toml` pointing at that runner object.
+</AgentPrompt>
 
 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`.
 
@@ -39,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`.
@@ -54,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.
@@ -88,31 +96,34 @@ 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 <JOB_ID>
+tilebox job spans <JOB_ID>
 ```
 
 ## Iterate safely
 
 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 <JOB_ID>
 ```
 
 For breaking input or behavior changes, bump the task major version and submit a new test job.