docs: chunky overhaul

.cursor/rules/docs-snippet-workflow.mdc

@@ -0,0 +1,33 @@
+---
+description: How to edit guide code examples and regenerate snippets
+globs: sdks/guides/**/*,frontend/docs/pages/guides/**/*.mdx,examples/*/guides/**/*
+alwaysApply: false
+---
+
+# Guide Snippet Workflow
+
+## Source of truth
+
+All guide code lives in `sdks/guides/{lang}/`. The files under `examples/{lang}/guides/` are **generated** mirrors. Never edit the `examples/` copies directly.
+
+## Snippet markers
+
+Use `# > Step Title` (or `// >` for TS/Go) to open a snippet and `# !!` (or `// !!`) to close it. The generator converts the title to snake_case for the snippet key (e.g. `# > Step 04 Rate Limited Scrape` → `step_04_rate_limited_scrape`).
+
+## Referencing snippets in MDX
+
+```
+snippets.{lang}.guides.{guide_dir}.{file_stem}.{snippet_key}
+```
+
+Example: `snippets.python.guides.web_scraping.worker.step_01_define_scrape_task`
+
+## Regenerating
+
+After editing any file in `sdks/guides/`, run:
+
+```
+cd frontend/snippets && python3 generate.py
+```
+
+This regenerates both `examples/*/guides/` mirror files and `frontend/docs/lib/generated/snippets/index.ts`.

.cursor/rules/docs-writing-style.mdc

@@ -0,0 +1,22 @@
+---
+description: Writing style conventions for Hatchet documentation
+globs: frontend/docs/**/*.mdx
+alwaysApply: false
+---
+
+# Docs Writing Style
+
+## Punctuation
+
+- Do NOT use em dashes (—). Use commas, parentheses, or separate sentences instead.
+- Prefer short, direct sentences over long compound ones.
+
+## Phrases to Avoid
+
+- Do not use "under the hood." Just state the fact directly.
+
+## Terminology
+
+- Do not use the word "cycle" to describe agent loops. Use "child spawning" or "self-spawning child task" instead.
+- Use "durable task" (not "durable function" or "durable workflow step") for the core execution primitive.
+- Link concept terms to their concept pages on first use (e.g. `[durable task](/concepts/durable-workflows/durable-task-execution)`).

.github/workflows/cli-e2e-tests.yml

@@ -3,24 +3,33 @@ name: cli-e2e-tests
 on:
   pull_request:
     paths:
+      - ".github/workflows/cli-e2e-tests.yml"
       - "cmd/hatchet-cli/cli/templates/**"
       - "cmd/hatchet-cli/cli/quickstart.go"
       - "cmd/hatchet-cli/cli/internal/templater/**"
       - "cmd/hatchet-cli/cli/quickstart_e2e_test.go"
-      - ".github/workflows/test-templates.yml"
+      - "cmd/hatchet-cli/cli/*.go"
+      - "cmd/hatchet-cli/cli/*_e2e_test.go"
+      - "cmd/hatchet-cli/cli/tui/**"
+      - "cmd/hatchet-cli/cli/testharness/**"
   push:
     branches:
       - main
     paths:
+      - ".github/workflows/cli-e2e-tests.yml"
       - "cmd/hatchet-cli/cli/templates/**"
       - "cmd/hatchet-cli/cli/quickstart.go"
       - "cmd/hatchet-cli/cli/internal/templater/**"
       - "cmd/hatchet-cli/cli/quickstart_e2e_test.go"
+      - "cmd/hatchet-cli/cli/*.go"
+      - "cmd/hatchet-cli/cli/*_e2e_test.go"
+      - "cmd/hatchet-cli/cli/tui/**"
+      - "cmd/hatchet-cli/cli/testharness/**"
 
 jobs:
   test-templates:
     runs-on: ubicloud-standard-4
-    timeout-minutes: 15
+    timeout-minutes: 30
 
     steps:
       - name: Checkout code
@@ -34,7 +43,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: "3.14"
+          python-version: "3.13" # pinned because of poetry dependency issue
 
       - name: Set up Node.js
         uses: actions/setup-node@v6
@@ -56,6 +65,9 @@ jobs:
       - name: Install Bun
         uses: oven-sh/setup-bun@v2
 
+      - name: Install tmux
+        run: sudo apt-get install -y tmux
+
       - name: Build CLI
         run: |
           cd cmd/hatchet-cli
@@ -79,9 +91,17 @@ jobs:
           cd cmd/hatchet-cli/cli
           go test -tags e2e_cli -run TestQuickstartTemplates -v -timeout 15m
         env:
-          # Ensure tests don't try to interact with stdin
           CI: true
 
+      - name: Run resource E2E tests
+        run: |
+          cd cmd/hatchet-cli/cli
+          go test -tags e2e_cli \
+            -run 'Test(Runs|Workflows|Worker|RateLimits|Scheduled|Cron|Webhooks)' \
+            -v -timeout 10m
+        env:
+          HATCHET_CLI_PROFILE: local
+
       - name: Show server logs on failure
         if: failure()
         run: |

.golangci.yml

@@ -55,7 +55,7 @@ linters:
     paths:
       - third_party$
       - builtin$
-      - examples$
+      - ^examples/
       - '(.+)_test\.go'
       - "cmd/hatchet-loadtest/rampup/(.+).go"
 formatters:
@@ -71,4 +71,4 @@ formatters:
     paths:
       - third_party$
       - builtin$
-      - examples$
+      - ^examples/

.pre-commit-config.yaml

@@ -17,5 +17,27 @@ repos:
     rev: v2.7.2
     hooks:
       - id: golangci-lint
-        args: ["--config=.golangci.yml"]
-        exclude: ^examples/
+        args: ["--config=.golangci.yml", "--allow-parallel-runners"]
+        exclude: ^(examples/|sdks/guides/go/)
+  - repo: local
+    hooks:
+      - id: golangci-lint-guides
+        name: golangci-lint (sdks/guides/go)
+        entry: bash -c 'cd sdks/guides/go && golangci-lint run ./... --config .golangci.yml --allow-parallel-runners'
+        language: system
+        files: ^sdks/guides/go/
+      - id: ruff-python-guides
+        name: ruff (sdks/guides/python)
+        entry: bash -c 'cd sdks/guides/python && poetry run ruff check .'
+        language: system
+        files: ^sdks/guides/python/
+      - id: eslint-typescript-guides
+        name: eslint (sdks/guides/typescript)
+        entry: bash -c 'cd sdks/guides/typescript && pnpm run lint:check'
+        language: system
+        files: ^sdks/guides/typescript/
+      - id: rubocop-ruby-guides
+        name: rubocop (sdks/guides/ruby)
+        entry: bash -c 'cd sdks/guides/ruby && bundle install && bundle exec rubocop'
+        language: system
+        files: ^sdks/guides/ruby/

Taskfile.yaml

@@ -61,9 +61,21 @@ tasks:
   fmt-docs:
     dir: frontend/docs
     cmd: pnpm run prettier:fix && pnpm run prettier:check
+  sync-agent-instructions:
+    desc: Sync agent-instructions MDX files into hatchet-cli skill-assets references
+    cmds:
+      - |
+        src="frontend/docs/pages/agent-instructions"
+        dest="cmd/hatchet-cli/cli/skill-assets/hatchet-cli/references"
+        for f in "$src"/*.mdx; do
+          name=$(basename "$f" .mdx)
+          cp "$f" "$dest/$name.md"
+        done
+
   pre:
     aliases: [fmt]
     cmds:
+      - task: sync-agent-instructions
       - task: fmt-go
       - task: fmt-app
       - task: fmt-docs
@@ -160,11 +172,12 @@ tasks:
       - task: generate-api-server
       - task: generate-api-client
   generate-docs:
-      deps: [venv]
-      dir: frontend/snippets
-      cmds:
-        - 'source {{.ROOT_DIR}}/.venv/bin/activate && python generate.py'
-        - task: fmt
+    deps: [venv]
+    dir: frontend/snippets
+    cmds:
+      - "source {{.ROOT_DIR}}/.venv/bin/activate && python generate.py"
+      - task: fmt
+      - task: sync-agent-instructions
   generate-certs:
     cmds:
       - bash ./hack/dev/generate-x509-certs.sh ./hack/dev/certs
@@ -199,10 +212,26 @@ tasks:
   lint:
     cmds:
       - task: lint-go
+      - task: lint-go-guides
+      - task: lint-python-guides
+      - task: lint-typescript-guides
+      - task: lint-ruby-guides
       - task: lint-app
       - task: lint-docs
   lint-go:
     cmd: golangci-lint run ./... --config .golangci.yml
+  lint-go-guides:
+    dir: sdks/guides/go
+    cmd: golangci-lint run ./... --config .golangci.yml
+  lint-python-guides:
+    dir: sdks/guides/python
+    cmd: poetry run ruff check .
+  lint-typescript-guides:
+    dir: sdks/guides/typescript
+    cmd: pnpm install && pnpm run lint:check
+  lint-ruby-guides:
+    dir: sdks/guides/ruby
+    cmd: bundle install && bundle exec rubocop
   lint-app:
     dir: frontend/app
     cmd: pnpm run lint:check
@@ -228,7 +257,7 @@ tasks:
     cmd: source .venv/bin/activate && pip install pre-commit && pre-commit install
   pre-commit-run:
     deps: [venv]
-    cmd: 'source .venv/bin/activate && pre-commit run --all-files || pre-commit run --all-files'
+    cmd: "source .venv/bin/activate && pre-commit run --all-files || pre-commit run --all-files"
   docs:
     cmds:
       - |

api/v1/server/oas/transformers/workflow_run.go

@@ -66,6 +66,11 @@ func ToCronWorkflowsFromSQLC(cron *sqlcv1.ListCronWorkflowsRow) *gen.CronWorkflo
 		}
 	}
 
+	input := make(map[string]interface{})
+	if cron.Input != nil {
+		json.Unmarshal(cron.Input, &input) //nolint:errcheck
+	}
+
 	res := &gen.CronWorkflows{
 		Metadata:           *toAPIMetadata(cron.ID_2, cron.CreatedAt_2.Time, cron.UpdatedAt_2.Time),
 		WorkflowVersionId:  cron.WorkflowVersionId.String(),
@@ -78,6 +83,7 @@ func ToCronWorkflowsFromSQLC(cron *sqlcv1.ListCronWorkflowsRow) *gen.CronWorkflo
 		Enabled:            cron.Enabled,
 		Method:             gen.CronWorkflowsMethod(cron.Method),
 		Priority:           &cron.Priority,
+		Input:              &input,
 	}
 
 	return res

build/package/servers.dockerfile

@@ -22,26 +22,18 @@ COPY /cmd ./cmd
 
 RUN go generate ./...
 
-# OpenAPI bundle environment
-# -------------------------
-FROM node:22-alpine as build-openapi
+# OpenAPI bundle environment (uses openapi-core only to avoid Redoc/React/styled-components)
+# ----------------------------------------------------------------------------------------
+FROM node:22-alpine AS build-openapi
 WORKDIR /openapi
 
 COPY /api-contracts/openapi ./openapi
+COPY /hack/oas/bundle-openapi.mjs ./bundle-openapi.mjs
 
-RUN echo '{ \
-    "name": "hack-for-redocly-cli-bug", \
-    "version": "1.0.0", \
-    "dependencies": { \
-    "@redocly/cli": "latest" \
-    }, \
-    "overrides": { \
-    "mobx-react": "9.2.0" \
-    } \
-    }' > package.json && \
-    npm install -g npm@8.1 @redocly/cli@latest && \
-    npx @redocly/cli@latest bundle ./openapi/openapi.yaml --output ./bin/oas/openapi.yaml --ext yaml && \
-    rm package.json
+RUN echo '{ "type": "module", "dependencies": { "@redocly/openapi-core": "2.14.7", "yaml": "2.7.0" } }' > package.json && \
+    npm install && \
+    node bundle-openapi.mjs && \
+    rm -f package.json package-lock.json bundle-openapi.mjs
 
 # Go build environment
 # --------------------

cmd/hatchet-cli/cli/client.go

@@ -1,17 +1,21 @@
 package cli
 
 import (
+	"github.com/google/uuid"
+	openapi_types "github.com/oapi-codegen/runtime/types"
 	"github.com/rs/zerolog"
+	"github.com/spf13/cobra"
 
-	"github.com/hatchet-dev/hatchet/pkg/client"
+	"github.com/hatchet-dev/hatchet/cmd/hatchet-cli/cli/internal/config/cli"
+	"github.com/hatchet-dev/hatchet/pkg/client" //nolint:staticcheck
 	profileconfig "github.com/hatchet-dev/hatchet/pkg/config/cli"
 	clientconfig "github.com/hatchet-dev/hatchet/pkg/config/client"
 	"github.com/hatchet-dev/hatchet/pkg/config/shared"
 )
 
 // NewClientFromProfile creates a new Hatchet client from a profile configuration.
 // It properly handles TLS settings, host/port, and authentication based on the profile.
-func NewClientFromProfile(profile *profileconfig.Profile, logger *zerolog.Logger) (client.Client, error) {
+func NewClientFromProfile(profile *profileconfig.Profile, logger *zerolog.Logger) (client.Client, error) { //nolint:staticcheck
 	// Construct a ClientConfigFile from the profile
 	configFile := &clientconfig.ClientConfigFile{
 		TenantId:  profile.TenantId,
@@ -26,5 +30,57 @@ func NewClientFromProfile(profile *profileconfig.Profile, logger *zerolog.Logger
 	}
 
 	// Create client with the config file and logger
-	return client.NewFromConfigFile(configFile, client.WithLogger(logger))
+	return client.NewFromConfigFile(configFile, client.WithLogger(logger)) //nolint:staticcheck
+}
+
+// clientCmdConfig holds CLI flag values used to create a Hatchet client.
+type clientCmdConfig struct {
+	Profile string
+}
+
+// readClientCmdConfig reads client-related flags from a command into a config struct.
+func readClientCmdConfig(cmd *cobra.Command) clientCmdConfig {
+	profile, _ := cmd.Flags().GetString("profile")
+	return clientCmdConfig{Profile: profile}
+}
+
+// clientFromCmd selects a profile and returns a Hatchet client.
+// The profile is read from the --profile flag if present, otherwise selected interactively.
+func clientFromCmd(cmd *cobra.Command) (string, client.Client) { //nolint:staticcheck
+	cfg := readClientCmdConfig(cmd)
+
+	var selectedProfile string
+	if cfg.Profile != "" {
+		selectedProfile = cfg.Profile
+	} else {
+		selectedProfile = selectProfileForm(true)
+		if selectedProfile == "" {
+			selectedProfile = handleNoProfiles(cmd)
+			if selectedProfile == "" {
+				cli.Logger.Fatal("no profile selected or created")
+			}
+		}
+	}
+
+	profile, err := cli.GetProfile(selectedProfile)
+	if err != nil {
+		cli.Logger.Fatalf("could not get profile '%s': %v", selectedProfile, err)
+	}
+
+	nopLogger := zerolog.Nop()
+	hatchetClient, err := NewClientFromProfile(profile, &nopLogger)
+	if err != nil {
+		cli.Logger.Fatalf("could not create Hatchet client: %v", err)
+	}
+
+	return selectedProfile, hatchetClient
+}
+
+// clientTenantUUID parses and returns the tenant UUID from the client configuration.
+func clientTenantUUID(hatchetClient client.Client) openapi_types.UUID { //nolint:staticcheck
+	parsed, err := uuid.Parse(hatchetClient.TenantId())
+	if err != nil {
+		cli.Logger.Fatalf("invalid tenant ID: %v", err)
+	}
+	return parsed
 }