[pull] main from TryGhost:main

.agents/skills/tinybird-cli-guidelines/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: tinybird-cli-guidelines
+description: Tinybird CLI commands, workflows, and operations. Use when running tb commands, managing local development, deploying, or working with data operations.
+---
+
+# Tinybird CLI Guidelines
+
+Guidance for using the Tinybird CLI (tb) for local development, deployments, data operations, and workspace management.
+
+## When to Apply
+
+- Running any `tb` command
+- Choosing a development workflow (local, branch, or cloud)
+- Local development with Tinybird Local
+- Branch development with Tinybird Cloud branches
+- Building and deploying projects
+- Setting up CI/CD pipelines
+- Appending, replacing, or deleting data
+- Managing tokens and secrets via CLI
+- Generating mock data
+- Running tests
+
+## Rule Files
+
+- `rules/development-workflows.md`
+- `rules/cli-commands.md`
+- `rules/build-deploy.md`
+- `rules/local-development.md`
+- `rules/branch-development.md`
+- `rules/ci-cd.md`
+- `rules/data-operations.md`
+- `rules/append-data.md`
+- `rules/mock-data.md`
+- `rules/tokens.md`
+- `rules/secrets.md`
+
+## Quick Reference
+
+- CLI 4.0 workflow: configure `dev_mode` once, then use plain `tb build` and `tb deploy`.
+- `tb build` targets your configured development environment (`branch` or `local`) in tinybird.config.json.
+- `tb deploy` targets Tinybird Cloud production.
+- Use `--cloud`/`--local`/`--branch` only as explicit manual overrides.
+- Use `tb info` to check CLI context.
+- Use `tb endpoint data <pipe>` to test endpoints (not `tb pipe data`).
+- Never invent commands or flags; run `tb <command> --help` to verify.

.agents/skills/tinybird-cli-guidelines/rules/append-data.md

@@ -0,0 +1,25 @@
+# Append Data
+
+Tinybird CLI supports three ways to append data to an existing datasource: local file, remote URL, or events payload.
+
+## CLI: tb datasource append
+
+```
+tb datasource append [datasource_name] --file /path/to/local/file
+```
+
+```
+tb datasource append [datasource_name] --url https://example.com/data.csv
+```
+
+```
+tb datasource append [datasource_name] --events '{"a":"b", "c":"d"}'
+```
+
+Notes:
+
+- The command appends to an existing datasource.
+- Use `tb --cloud datasource append` to target Cloud; Local is the default.
+- For ingesting data from Kafka, S3 or GCS, see: https://www.tinybird.co/docs/forward/get-data-in/connectors
+
+You can also send POST request to v0/events (streaming) and v0/datasources (batch) endpoints.

.agents/skills/tinybird-cli-guidelines/rules/branch-development.md

@@ -0,0 +1,108 @@
+# Branch Development
+
+## Overview
+
+Tinybird Cloud branches provide isolated environments for development and testing. Each branch gets its own copy of resources and can optionally include production data. Branches are the recommended workflow for teams collaborating on the same workspace.
+
+## When to Use Branches
+
+- Developing features that need real production data shapes for testing
+- Collaborating with a team where multiple people work on the same workspace
+- Testing schema changes or new endpoints before deploying to production
+- CI/CD workflows that validate changes on pull requests
+
+For solo development or quick iteration, Tinybird Local (`dev_mode=local`) may be faster. See `rules/local-development.md`.
+
+## Branch Workflow
+
+1. Create a git branch for your feature
+2. Run `tb dev` — Tinybird automatically creates a Cloud branch matching your git branch name
+3. Develop and test against the branch (file changes are watched and auto-rebuilt)
+4. Push changes and create a PR
+5. Merge to deploy to production
+
+## Creating Branches
+
+Automatic (recommended):
+
+Check out a git branch and run `tb dev` or `tb build`. Tinybird automatically creates or uses a Cloud branch with the same name as your git branch.
+
+Manual:
+
+```
+tb branch create my_feature
+```
+
+Branch names must use underscores, not hyphens (e.g., `my_feature`, not `my-feature`).
+
+### The `--last-partition` Flag
+
+Use `--last-partition` to copy the latest partition of production data into the branch:
+
+```
+tb branch create my_feature --last-partition
+```
+
+This is useful when you need real data to test queries, validate endpoint behavior, or debug issues that depend on production data shapes. Without it, the branch starts empty.
+
+### The `--with-connections` Flag
+
+Use `--with-connections` to enable connectors (Kafka, S3, GCS) in the branch:
+
+```
+tb branch create my_feature --last-partition --with-connections
+```
+
+For S3/GCS, import sample data with `tb --branch=my_feature datasource sample <datasource> --wait`. Kafka connections are stopped by default and need to be started explicitly with `tb --branch=my_feature datasource start <datasource>`.
+
+## Working with Branch Tokens
+
+After creating a branch, you may need its token to connect client applications (dashboards, APIs, scripts) to the branch environment instead of production.
+
+List tokens for a branch:
+
+```
+tb --branch my_feature token ls
+```
+
+### Using Branch Tokens in Client Apps
+
+A common pattern is to set an environment variable that your application checks, falling back to the production token when no branch token is set:
+
+```env
+# .env.local
+TINYBIRD_API_URL=https://api.tinybird.co
+TINYBIRD_API_TOKEN=<production-read-token>
+TINYBIRD_BRANCH_TOKEN=<branch-token>
+```
+
+In your application, prioritize the branch token when present:
+
+```
+token = TINYBIRD_BRANCH_TOKEN || TINYBIRD_API_TOKEN
+```
+
+This way, setting or unsetting the branch token switches between branch and production data without code changes.
+
+## Branch Commands Reference
+
+- `tb branch ls`: List all branches
+- `tb branch create <name>`: Create a new branch (empty)
+- `tb branch create <name> --last-partition`: Create a branch with latest production data
+- `tb branch create <name> --last-partition --with-connections`: Create a branch with data and connectors
+- `tb branch rm <name>`: Remove a branch
+- `tb branch clear`: Clear branch state
+- `tb dev`: Start development session (auto-creates branch from git branch name, watches files)
+- `tb --branch <name> open`: Open the branch in the Tinybird UI
+
+## Targeting a Branch Explicitly
+
+Most commands can target a specific branch with the `--branch` flag:
+
+```
+tb --branch my_feature endpoint data my_endpoint
+tb --branch my_feature sql "SELECT count() FROM my_datasource"
+tb --branch my_feature token ls
+```
+
+When `dev_mode=branch`, `tb build` targets the branch automatically without needing `--branch`.

.agents/skills/tinybird-cli-guidelines/rules/build-deploy.md

@@ -0,0 +1,56 @@
+# Build & Deploy
+
+Use this rule to keep local files, development environments, and production deployments aligned under the CLI 4.0 workflow.
+
+## Default Workflow (CLI 4.0)
+
+1. Configure `dev_mode` in `tinybird.config.json` (`branch`, `local`, or `manual`).
+2. Run `tb build` to validate and sync to the configured development target.
+3. Run `tb deploy` to deploy to Tinybird Cloud main (production).
+
+In CLI 4.0, build/deploy should usually be run without `--cloud`, `--local`, or `--branch`.
+
+## `tb build` Behavior
+
+- `dev_mode=local`: builds against Tinybird Local.
+- `dev_mode=branch`: builds against a Cloud branch derived from the current git branch (created automatically if needed).
+- `dev_mode=manual`: requires explicit flags (`--local`, `--cloud`, `--branch`) for environment selection.
+- In branch mode, building from `main`/`master` is blocked to avoid accidental production changes.
+
+## `tb deploy` Behavior
+
+- `tb deploy` deploys current project files to Tinybird Cloud main.
+- Use only when the user explicitly requests a production deployment.
+- Ask for confirmation before deploying.
+
+## Deploy Check
+
+- Run `tb deploy --check` before real deploys to catch schema/dependency issues early.
+- Use check mode whenever deployment intent is uncertain.
+
+## Destructive operations and flags
+
+- Deleting datasources, pipes, or connections locally requires an explicit destructive deploy.
+- Use `tb deploy --allow-destructive-operations` only when the user confirms deletion or data loss is acceptable.
+- If you see warnings about deletions, stop and ask for confirmation before re-running with the flag.
+
+Example:
+
+```
+tb deploy --allow-destructive-operations
+```
+
+## Manual Overrides
+
+- Explicit flags still work and override `dev_mode`.
+- Use overrides only when the user explicitly asks for a specific environment target.
+
+## Validation intent (why)
+
+- Building keeps development environments aligned with local files for fast iteration.
+- Deploy checks reduce failed deployments by validating changes before publishing.
+
+## What not to do
+
+- Do not deploy destructive changes without `--allow-destructive-operations` and explicit user confirmation.
+- Do not assume production is updated after `tb build`; `build` and `deploy` are separate operations.