adding SKILL files

.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "wherobots-cli",
+  "description": "Skills for submitting, monitoring, and debugging Wherobots Cloud job runs via the wherobots CLI",
+  "version": "1.0.0",
+  "author": {
+    "name": "Wherobots"
+  }
+}

.claude/skills/exploring-api/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: exploring-api
+description: Discovers and calls Wherobots API endpoints using the CLI's dynamically generated commands. Covers files, storage integrations, organization details, and any endpoint beyond job runs. Use when a user needs API operations not covered by the job-runs commands.
+---
+
+# Exploring the Wherobots API
+
+The `wherobots api` command tree is generated from the Wherobots OpenAPI spec. Every API endpoint has a corresponding CLI command.
+
+## Discovery
+
+```bash
+wherobots api --tree                        # Full command hierarchy
+wherobots api <resource> <verb> --help      # Flags and body template for a command
+wherobots api <resource> <verb> --dry-run   # Preview as curl (API key sanitized)
+```
+
+## Common operations
+
+### SQL session lifecycle
+```bash
+wherobots api sql --tree                    # Discover available SQL session operations
+```
+
+Use `api sql` commands to manage SQL sessions (create, stop, check status). Do not use these for query execution — use Python DB-API, JDBC, or the MCP server instead. See the `using-wherobots` skill for routing guidance.
+
+### Files and storage
+```bash
+wherobots api files dir get -q dir=s3://my-bucket/path/
+wherobots api files integration-dir get -q integration_id=<id> -q dir=/
+wherobots api files upload-url create -q key=path/to/file.py
+```
+
+### Organization
+```bash
+wherobots api organization get    # Includes fileStore and storageIntegrations
+```
+
+### Runs (low-level)
+```bash
+wherobots api runs list -q size=10 -q status=RUNNING
+wherobots api runs get --run-id <id>
+wherobots api runs logs get --run-id <id> -q cursor=0 -q size=100
+wherobots api runs metrics get --run-id <id>
+```
+
+## Flag conventions
+
+- Path parameters → `--param-name`
+- Query parameters → `--param-name` or `-q key=value`
+- Body fields → `--field-name` (scalars) or `--field-name-json` (objects/arrays)
+- `--json '{...}'` overrides all body field flags
+
+## Guidance
+
+- For job-run workflows, prefer the dedicated `job-runs` commands (better UX).
+- For query execution, use Python DB-API, JDBC, or the MCP server — not the CLI.
+- The CLI `api sql` commands are for session **lifecycle** (start, stop, status), not query execution.
+- Suggest `--dry-run` first when the user is exploring or unsure.
+- `WHEROBOTS_API_KEY` must be set. The `wherobots` CLI must be installed.

.claude/skills/monitoring-jobs/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: monitoring-jobs
+description: Lists, filters, and checks the status of Wherobots job runs. Includes shortcuts for running, failed, and completed jobs, plus instant metrics. Use when a user wants to see their jobs, check what's running, find failures, or get resource metrics.
+---
+
+# Monitoring Wherobots Job Runs
+
+## Commands
+
+### List jobs
+```bash
+wherobots job-runs list [flags]
+```
+
+**Filters:**
+- `-s, --status` — `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, `PENDING` (repeatable)
+- `--name` — filter by name pattern
+- `--after` — ISO timestamp (e.g., `2025-01-15T00:00:00Z`)
+- `-l, --limit` — max results (default: `20`)
+- `--region` — filter by region
+- `--output` — `text` (default, tabular) or `json`
+
+### Status shortcuts
+```bash
+wherobots job-runs running       # RUNNING jobs only
+wherobots job-runs failed        # FAILED jobs only
+wherobots job-runs completed     # COMPLETED jobs only
+```
+
+Each accepts `--name`, `--after`, `-l`, `--region`, `--output`.
+
+### Instant metrics
+```bash
+wherobots job-runs metrics <run-id>
+```
+
+Displays CPU, memory, and other metrics for an active run. Supports `--output json`.
+
+## Examples
+
+```bash
+wherobots job-runs list                                          # Recent jobs
+wherobots job-runs failed -l 5                                   # Last 5 failures
+wherobots job-runs list --name nightly --after 2025-01-01T00:00:00Z
+wherobots job-runs running --region aws-us-west-2
+wherobots job-runs metrics abc-123-def
+wherobots job-runs list --output json                            # For scripting
+```
+
+## Guidance
+
+- Text output is a table: ID, NAME, STATUS, CREATED, RUNTIME, REGION.
+- To dig into a specific job, suggest viewing logs or metrics by run ID.
+- `WHEROBOTS_API_KEY` must be set. The `wherobots` CLI must be installed.

.claude/skills/submitting-jobs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: submitting-jobs
+description: Submits Wherobots Cloud job runs from local Python files or S3 URIs. Resolves storage using the customer's S3 Storage Integration first, falling back to Wherobots managed storage. Use when a user wants to run, submit, or execute a Python script on Wherobots Cloud.
+---
+
+# Submitting Wherobots Job Runs
+
+## Storage resolution order
+
+Job runs execute from S3. The CLI accepts a local `.py` file or an `s3://` URI — local files are uploaded automatically. Resolve where the script will live in this order:
+
+### 1. Customer's own S3 via Storage Integration (preferred)
+
+If the customer has an S3 Storage Integration configured:
+- Direct `s3://` URI: `s3://their-bucket/scripts/my_job.py`
+- Upload override: `--upload-path s3://their-bucket/prefix`
+- Environment variable: `WHEROBOTS_UPLOAD_PATH`
+
+### 2. Wherobots managed storage (fallback)
+
+If no Storage Integration exists or the customer is unsure, the CLI automatically resolves the managed storage bucket via the organization API. No extra configuration needed — just pass the local `.py` file.
+
+## Command reference
+
+```bash
+wherobots job-runs create <script> -n <name> [flags]
+```
+
+### Required
+- `<script>` — local `.py` file path or `s3://` URI (positional)
+- `-n, --name` — job run name
+
+### Optional
+- `-r, --runtime` — compute size (default: `tiny`)
+- `--run-region` — region (default: `aws-us-west-2`)
+- `--timeout` — seconds (default: `3600`)
+- `--args` — space-separated arguments for the script
+- `-c, --spark-config` — `key=value` (repeatable)
+- `--dep-pypi` — `name==version` (repeatable)
+- `--dep-file` — S3 URI for `.jar`, `.whl`, `.zip`, `.json` (repeatable)
+- `-w, --watch` — stream logs until completion
+- `--upload-path` — override S3 upload destination
+- `--no-upload` — skip auto-upload (script already in S3)
+- `--output` — `text` (default) or `json`
+
+## Examples
+
+**Local file, managed storage:**
+```bash
+wherobots job-runs create ./my_script.py -n my-job -w
+```
+
+**Local file, customer S3:**
+```bash
+wherobots job-runs create ./my_script.py -n my-job --upload-path s3://my-bucket/jobs -w
+```
+
+**Script already in S3:**
+```bash
+wherobots job-runs create s3://my-bucket/scripts/my_script.py -n my-job --no-upload -w
+```
+
+**With dependencies and Spark config:**
+```bash
+wherobots job-runs create ./etl.py -n nightly-etl \
+  -r medium \
+  --timeout 7200 \
+  --dep-pypi pandas==2.1.0 \
+  --dep-file s3://my-bucket/libs/utils.whl \
+  -c spark.sql.shuffle.partitions=200 \
+  -w
+```
+
+## Guidance
+
+- This skill is for batch job execution. If the user wants to run an interactive query, use the MCP server or Python DB-API instead — see the `using-wherobots` skill.
+- Ask whether the customer has an S3 Storage Integration or should use managed storage.
+- Default to `-w` (watch) so they see logs in real time.
+- Only ask about runtime size if they mention performance needs or large data.
+- Only ask about dependencies if they mention libraries their script needs.
+- `WHEROBOTS_API_KEY` must be set. The `wherobots` CLI must be installed.

.claude/skills/using-wherobots/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: using-wherobots
+description: Routes to the right Wherobots tool for the task. Covers when to use the wherobots CLI, MCP server, Python DB-API, JDBC, or SDKs. Use when a user wants to interact with Wherobots Cloud and you need to determine the right approach.
+---
+
+# Using Wherobots Tools
+
+Multiple tools exist for working with Wherobots Cloud. Choose based on what the task requires.
+
+## Tool selection
+
+### Wherobots MCP Server — interactive exploration and ad-hoc queries
+
+Use for: catalog discovery, schema inspection, spatial SQL generation, small-scale query execution, documentation lookup.
+
+- Runs on a Tiny runtime with ~10-minute time limits
+- 1000-row result limit on returned data
+- Best for exploratory and conversational workflows in Claude Code or VS Code
+- Tools: `search_documentation_tool`, `list_catalogs_tool`, `list_tables_tool`, `describe_table_tool`, `generate_spatial_query_tool`, `execute_query_tool`
+
+### Python DB-API / JDBC — programmatic query execution
+
+Use for: running spatial SQL from application code, retrieving query results in Python or Java, building data pipelines.
+
+**Python (`wherobots-python-dbapi`):**
+```python
+from wherobots.db import connect
+from wherobots.db.region import Region
+from wherobots.db.runtime import Runtime
+
+with connect(
+    host="api.cloud.wherobots.com",
+    api_key=api_key,
+    runtime=Runtime.TINY,
+    region=Region.AWS_US_WEST_2) as conn:
+    curr = conn.cursor()
+    curr.execute("SELECT ... FROM ...")
+    results = curr.fetchall()
+```
+
+**JDBC:** `jdbc:wherobots://api.cloud.wherobots.com` with `apiKey`, `runtime`, `region` properties.
+
+These are the right choice when code needs to execute queries and process results. The MCP server or CLI should not be used for query execution in application code.
+
+### `wherobots` CLI `job-runs` — batch execution
+
+Use for: submitting Python or JAR scripts for large-scale processing, ETL, long-running computation, anything needing a dedicated runtime.
+
+See the `submitting-jobs`, `monitoring-jobs`, and `viewing-logs` skills.
+
+### `wherobots` CLI `api` — REST API access and session lifecycle
+
+Use for: SQL session lifecycle management (create, stop, check status), file and storage operations, organization management, any API operation not covered above.
+
+Key distinction: use `api sql ...` commands to **manage** SQL sessions (start, stop, status). Use DB-API, JDBC, or MCP to **execute queries** within those sessions.
+
+See the `exploring-api` skill.
+
+### Airflow operators — orchestrated workflows
+
+Use for: scheduled pipelines, DAGs, production ETL orchestration.
+
+- `WherobotsRunOperator` — submits job runs from Airflow
+- `WherobotsSqlOperator` — executes SQL queries from Airflow
+
+## Decision shortcuts
+
+| Task | Tool |
+|---|---|
+| "What tables are available?" | MCP (`list_tables_tool`) |
+| "Run this spatial query" (interactive) | MCP (`execute_query_tool`) |
+| "Run this query in my Python app" | DB-API or JDBC |
+| "Submit this script as a batch job" | CLI `job-runs create` |
+| "Check my running jobs" | CLI `job-runs list` |
+| "Start/stop a SQL session" | CLI `api sql ...` |
+| "Manage files in S3" | CLI `api files ...` |
+| "Schedule a nightly pipeline" | Airflow operators |

.claude/skills/viewing-logs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: viewing-logs
+description: Fetches or streams logs for a Wherobots job run. Supports following in real time and tailing the last N lines. Use when a user wants to see logs, debug a failed job, tail output, or follow a running job's progress.
+---
+
+# Viewing Wherobots Job Run Logs
+
+## Command
+
+```bash
+wherobots job-runs logs <run-id> [flags]
+```
+
+### Flags
+- `-f, --follow` — stream logs in real time until completion (Ctrl+C to detach)
+- `-t, --tail <N>` — last N log lines (batch mode only)
+- `--interval <seconds>` — poll interval when following (default: `2`)
+- `--output` — `text` (default) or `json` (not supported with `--follow`)
+
+## Examples
+
+```bash
+wherobots job-runs logs abc-123-def                  # All logs
+wherobots job-runs logs abc-123-def --follow         # Stream live
+wherobots job-runs logs abc-123-def --tail 50        # Last 50 lines
+wherobots job-runs logs abc-123-def -f --interval 1  # Faster polling
+```
+
+## Debugging a failed job
+
+1. Find the job: `wherobots job-runs failed -l 5`
+2. View the tail: `wherobots job-runs logs <run-id> --tail 100`
+3. Look for stack traces, error messages, or OOM indicators
+4. Check metrics if needed: `wherobots job-runs metrics <run-id>`
+
+## Guidance
+
+- If the user doesn't have a run ID, suggest `wherobots job-runs list` to find one.
+- Recommend `--follow` for running jobs, `--tail` for completed/failed jobs.
+- `WHEROBOTS_API_KEY` must be set. The `wherobots` CLI must be installed.

skills/exploring-api/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: exploring-api
+description: Discovers and calls Wherobots API endpoints using the CLI's dynamically generated commands. Covers files, storage integrations, organization details, and any endpoint beyond job runs. Use when a user needs API operations not covered by the job-runs commands.
+---
+
+# Exploring the Wherobots API
+
+The `wherobots api` command tree is generated from the Wherobots OpenAPI spec. Every API endpoint has a corresponding CLI command.
+
+## Discovery
+
+```bash
+wherobots api --tree                        # Full command hierarchy
+wherobots api <resource> <verb> --help      # Flags and body template for a command
+wherobots api <resource> <verb> --dry-run   # Preview as curl (API key sanitized)
+```
+
+## Common operations
+
+### SQL session lifecycle
+```bash
+wherobots api sql --tree                    # Discover available SQL session operations
+```
+
+Use `api sql` commands to manage SQL sessions (create, stop, check status). Do not use these for query execution — use Python DB-API, JDBC, or the MCP server instead. See the `using-wherobots` skill for routing guidance.
+
+### Files and storage
+```bash
+wherobots api files dir get -q dir=s3://my-bucket/path/
+wherobots api files integration-dir get -q integration_id=<id> -q dir=/
+wherobots api files upload-url create -q key=path/to/file.py
+```
+
+### Organization
+```bash
+wherobots api organization get    # Includes fileStore and storageIntegrations
+```
+
+### Runs (low-level)
+```bash
+wherobots api runs list -q size=10 -q status=RUNNING
+wherobots api runs get --run-id <id>
+wherobots api runs logs get --run-id <id> -q cursor=0 -q size=100
+wherobots api runs metrics get --run-id <id>
+```
+
+## Flag conventions
+
+- Path parameters → `--param-name`
+- Query parameters → `--param-name` or `-q key=value`
+- Body fields → `--field-name` (scalars) or `--field-name-json` (objects/arrays)
+- `--json '{...}'` overrides all body field flags
+
+## Guidance
+
+- For job-run workflows, prefer the dedicated `job-runs` commands (better UX).
+- For query execution, use Python DB-API, JDBC, or the MCP server — not the CLI.
+- The CLI `api sql` commands are for session **lifecycle** (start, stop, status), not query execution.
+- Suggest `--dry-run` first when the user is exploring or unsure.
+- `WHEROBOTS_API_KEY` must be set. The `wherobots` CLI must be installed.