docs: chunky overhaul (#3129)

* improve overall docs structure and things

Author: grutt

.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/pnpm/pnpm-lock.yaml

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