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)`).

.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,5 @@ 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/)

Taskfile.yaml

@@ -212,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

cmd/hatchet-cli/cli/templates/typescript/bun/package.json

@@ -16,6 +16,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hatchet-dev/typescript-sdk": "^1.10.3"
+    "@hatchet-dev/typescript-sdk": "1.10.3"
   }
 }

cmd/hatchet-cli/cli/templates/typescript/npm/package.json

@@ -16,6 +16,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hatchet-dev/typescript-sdk": "^1.10.3"
+    "@hatchet-dev/typescript-sdk": "1.10.3"
   }
 }

cmd/hatchet-cli/cli/templates/typescript/pnpm/package.json

@@ -16,7 +16,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hatchet-dev/typescript-sdk": "^1.10.3"
+    "@hatchet-dev/typescript-sdk": "1.10.3"
   },
   "pnpm": {
     "overrides": {

cmd/hatchet-cli/cli/templates/typescript/yarn/package.json

@@ -16,6 +16,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@hatchet-dev/typescript-sdk": "^1.10.3"
+    "@hatchet-dev/typescript-sdk": "1.10.3"
   }
 }

examples/go/guides/ai-agents/main.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"log"
+
+	"github.com/hatchet-dev/hatchet/pkg/cmdutils"
+	hatchet "github.com/hatchet-dev/hatchet/sdks/go"
+)
+
+func main() {
+	client, err := hatchet.NewClient()
+	if err != nil {
+		log.Fatalf("failed to create hatchet client: %v", err)
+	}
+
+	// > Step 02 Reasoning Loop
+	agentReasoningLoop := func(query string) (map[string]interface{}, error) {
+		messages := []map[string]interface{}{{"role": "user", "content": query}}
+		for i := 0; i < 10; i++ {
+			resp := CallLLM(messages)
+			if resp.Done {
+				return map[string]interface{}{"response": resp.Content}, nil
+			}
+			for _, tc := range resp.ToolCalls {
+				args := make(map[string]interface{})
+				for k, v := range tc.Args {
+					args[k] = v
+				}
+				result := RunTool(tc.Name, args)
+				messages = append(messages, map[string]interface{}{"role": "tool", "content": result})
+			}
+		}
+		return map[string]interface{}{"response": "Max iterations reached"}, nil
+	}
+
+	// > Step 01 Define Agent Task
+	agentTask := client.NewStandaloneDurableTask("reasoning-loop-agent", func(ctx hatchet.DurableContext, input map[string]interface{}) (map[string]interface{}, error) {
+		query := "Hello"
+		if q, ok := input["query"].(string); ok && q != "" {
+			query = q
+		}
+		return agentReasoningLoop(query)
+	})
+
+	// > Step 03 Stream Response
+	streamingTask := client.NewStandaloneDurableTask("streaming-agent-task", func(ctx hatchet.DurableContext, input map[string]interface{}) (map[string]interface{}, error) {
+		tokens := []string{"Hello", " ", "world", "!"}
+		for _, t := range tokens {
+			ctx.PutStream(t)
+		}
+		return map[string]interface{}{"done": true}, nil
+	})
+
+	// > Step 04 Run Worker
+	worker, err := client.NewWorker("agent-worker",
+		hatchet.WithWorkflows(agentTask, streamingTask),
+		hatchet.WithSlots(5),
+		hatchet.WithDurableSlots(5),
+	)
+	if err != nil {
+		log.Fatalf("failed to create worker: %v", err)
+	}
+
+	interruptCtx, cancel := cmdutils.NewInterruptContext()
+	defer cancel()
+
+	if err := worker.StartBlocking(interruptCtx); err != nil {
+		cancel()
+		log.Fatalf("failed to start worker: %v", err)
+	}
+}

examples/go/guides/ai-agents/mock_agent.go

@@ -0,0 +1,40 @@
+package main
+
+// CallLLM is a mock - no external LLM API.
+// First call returns tool_calls; second returns final answer.
+var llmCallCount int
+
+type LLMResponse struct {
+	Content   string
+	ToolCalls []ToolCall
+	Done      bool
+}
+
+type ToolCall struct {
+	Name string
+	Args map[string]interface{}
+}
+
+func CallLLM(messages []map[string]interface{}) LLMResponse {
+	llmCallCount++
+	if llmCallCount == 1 {
+		return LLMResponse{
+			Content:   "",
+			ToolCalls: []ToolCall{{Name: "get_weather", Args: map[string]interface{}{"location": "SF"}}},
+			Done:      false,
+		}
+	}
+	return LLMResponse{Content: "It's 72°F and sunny in SF.", ToolCalls: nil, Done: true}
+}
+
+// RunTool is a mock - returns canned results.
+func RunTool(name string, args map[string]interface{}) string {
+	if name == "get_weather" {
+		loc := "unknown"
+		if v, ok := args["location"]; ok {
+			loc = v.(string)
+		}
+		return "Weather in " + loc + ": 72°F, sunny"
+	}
+	return "Unknown tool: " + name
+}

examples/go/guides/batch-processing/main.go

@@ -0,0 +1,67 @@
+package main
+
+import (
+	"log"
+
+	"github.com/hatchet-dev/hatchet/pkg/cmdutils"
+	hatchet "github.com/hatchet-dev/hatchet/sdks/go"
+)
+
+type BatchInput struct {
+	Items []string `json:"items"`
+}
+
+type ItemInput struct {
+	ItemID string `json:"item_id"`
+}
+
+func main() {
+	client, err := hatchet.NewClient()
+	if err != nil {
+		log.Fatalf("failed to create hatchet client: %v", err)
+	}
+
+	// > Step 03 Process Item
+	childTask := client.NewStandaloneTask("process-item", func(ctx hatchet.Context, input ItemInput) (map[string]string, error) {
+		return map[string]string{"status": "done", "item_id": input.ItemID}, nil
+	})
+
+	// > Step 01 Define Parent Task
+	parentTask := client.NewStandaloneDurableTask("spawn-children", func(ctx hatchet.DurableContext, input BatchInput) (map[string]interface{}, error) {
+		inputs := make([]hatchet.RunManyOpt, len(input.Items))
+		for i, itemID := range input.Items {
+			inputs[i] = hatchet.RunManyOpt{Input: ItemInput{ItemID: itemID}}
+		}
+		runRefs, err := childTask.RunMany(ctx, inputs)
+		if err != nil {
+			return nil, err
+		}
+		results := make([]interface{}, len(runRefs))
+		for i, ref := range runRefs {
+			result, err := ref.Result()
+			if err != nil {
+				return nil, err
+			}
+			var parsed map[string]interface{}
+			if err := result.TaskOutput("process-item").Into(&parsed); err != nil {
+				return nil, err
+			}
+			results[i] = parsed
+		}
+		return map[string]interface{}{"processed": len(results), "results": results}, nil
+	})
+
+	// > Step 04 Run Worker
+	worker, err := client.NewWorker("batch-worker", hatchet.WithWorkflows(parentTask, childTask), hatchet.WithSlots(20))
+	if err != nil {
+		log.Fatalf("failed to create worker: %v", err)
+	}
+
+	interruptCtx, cancel := cmdutils.NewInterruptContext()
+	defer cancel()
+
+	if err := worker.StartBlocking(interruptCtx); err != nil {
+		cancel()
+		log.Fatalf("failed to start worker: %v", err)
+	}
+}

examples/go/guides/document-processing/main.go

@@ -0,0 +1,63 @@
+package main
+
+import (
+	"log"
+
+	"github.com/hatchet-dev/hatchet/pkg/cmdutils"
+	hatchet "github.com/hatchet-dev/hatchet/sdks/go"
+)
+
+type DocInput struct {
+	DocID   string `json:"doc_id"`
+	Content []byte `json:"content"`
+}
+
+func main() {
+	client, err := hatchet.NewClient()
+	if err != nil {
+		log.Fatalf("failed to create hatchet client: %v", err)
+	}
+
+	// > Step 01 Define DAG
+	workflow := client.NewWorkflow("DocumentPipeline")
+
+	// > Step 02 Parse Stage
+	ingest := workflow.NewTask("ingest", func(ctx hatchet.Context, input DocInput) (map[string]interface{}, error) {
+		return map[string]interface{}{"doc_id": input.DocID, "content": input.Content}, nil
+	})
+
+	parse := workflow.NewTask("parse", func(ctx hatchet.Context, input DocInput) (map[string]interface{}, error) {
+		var ingested map[string]interface{}
+		if err := ctx.ParentOutput(ingest, &ingested); err != nil {
+			return nil, err
+		}
+		content := ingested["content"].([]byte)
+		text := parseDocument(content)
+		return map[string]interface{}{"doc_id": input.DocID, "text": text}, nil
+	}, hatchet.WithParents(ingest))
+
+	// > Step 03 Extract Stage
+	extract := workflow.NewTask("extract", func(ctx hatchet.Context, input DocInput) (map[string]interface{}, error) {
+		var parsed map[string]interface{}
+		if err := ctx.ParentOutput(parse, &parsed); err != nil {
+			return nil, err
+		}
+		return map[string]interface{}{"doc_id": parsed["doc_id"], "entities": []string{"entity1", "entity2"}}, nil
+	}, hatchet.WithParents(parse))
+
+	_ = extract
+
+	// > Step 04 Run Worker
+	worker, err := client.NewWorker("document-worker", hatchet.WithWorkflows(workflow))
+	if err != nil {
+		log.Fatalf("failed to create worker: %v", err)
+	}
+
+	interruptCtx, cancel := cmdutils.NewInterruptContext()
+	defer cancel()
+
+	if err := worker.StartBlocking(interruptCtx); err != nil {
+		cancel()
+		log.Fatalf("failed to start worker: %v", err)
+	}
+}