pgflow-dev
diff --git a/‎CLAUDE.md
Lines changed: 21 additions & 0 deletions b/‎CLAUDE.md
Lines changed: 21 additions & 0 deletions
diff --git a/‎examples/playground/package.json
Lines changed: 1 addition & 1 deletion b/‎examples/playground/package.json
Lines changed: 1 addition & 1 deletion
diff --git a/‎pkgs/edge-worker/supabase/call
Lines changed: 1 addition & 2 deletions b/‎pkgs/edge-worker/supabase/call
Lines changed: 1 addition & 2 deletions
diff --git a/‎pkgs/website/astro.config.mjs
Lines changed: 24 additions & 6 deletions b/‎pkgs/website/astro.config.mjs
Lines changed: 24 additions & 6 deletions
diff --git a/‎pkgs/website/src/content/docs/edge-worker/getting-started/create-first-worker.mdx
Lines changed: 1 addition & 1 deletion b/‎pkgs/website/src/content/docs/edge-worker/getting-started/create-first-worker.mdx
Lines changed: 1 addition & 1 deletion
diff --git a/‎pkgs/website/src/content/docs/getting-started/run-flow.mdx
Lines changed: 22 additions & 2 deletions b/‎pkgs/website/src/content/docs/getting-started/run-flow.mdx
Lines changed: 22 additions & 2 deletions
diff --git a/‎pkgs/website/src/content/docs/how-to/naming-steps.mdx
Lines changed: 41 additions & 0 deletions b/‎pkgs/website/src/content/docs/how-to/naming-steps.mdx
Lines changed: 41 additions & 0 deletions
@@ -15,6 +15,26 @@ Never use:
 
 The only exception is in class names, where "Pgflow" can be used (PascalCase).
 
+## ⚠️ CHARACTER USAGE GUIDELINES ⚠️
+
+**IMPORTANT**: Never use the following characters in documentation or code comments. Always use the alternatives listed below:
+
+- **Em-dash (—)**: Use hyphen (-) instead
+- **Curly quotes ("" '')**: Use straight quotes ("" '') instead
+- **Right single quote/curly apostrophe (')**: Use straight apostrophe (') instead
+- **Ellipsis character (…)**: Use three periods (...) instead
+- **Non-breaking space**: Use regular space instead
+
+This ensures compatibility across different editors and environments.
+
+### Quick Fix Command
+
+To replace all these characters in a file, use this script:
+
+```bash
+./scripts/replace-special-chars.sh <file_path>
+```
+
 ## ⚠️ MVP STATUS AND DEVELOPMENT PHILOSOPHY ⚠️
 
 **IMPORTANT**: pgflow is currently a Minimum Viable Product (MVP) in very early stages of development. When working on this codebase:
@@ -48,6 +68,7 @@ When suggesting changes or improvements, bias heavily toward solutions that can
 - **Naming**: Use camelCase for variables/functions, PascalCase for classes/types
 - **Error Handling**: Use proper error types and handle errors appropriately
 - **File Structure**: Monorepo structure with packages in pkgs/ directory
+- **Documentation Style**: Use impersonal, factual language. Avoid "we" and "our" when describing technical concepts, flows, or processes. Only use "you" when directly instructing the reader. Focus on what the system does, not who is doing it.
 
 ## Packages
 
 
@@ -6,7 +6,7 @@
     "build": "next build",
     "start": "next start",
     "start-functions": "npx supabase@latest functions serve",
-    "start-workers": "for workerIndex in 0 1; do curl http://127.0.0.1:54321/functions/v1/analyze_website_worker_$workerIndex; done",
+    "start-workers": "for workerIndex in 0 1; do curl -X POST http://127.0.0.1:54321/functions/v1/analyze_website_worker_$workerIndex; done",
     "gen-types": "npx supabase@latest gen types --local --schema public --schema pgflow > supabase/functions/database-types.d.ts"
   },
   "dependencies": {
 
@@ -15,8 +15,7 @@ function_name="$1"
 data="$2"
 
 API_URL=http://localhost:50321
-curl \
-  --request POST \
+curl -X POST \
   "${API_URL}/functions/v1/${function_name}" \
   --header 'Authorization: Bearer '${ANON_KEY}'' \
   --header 'Content-Type: application/json' \
 
@@ -95,16 +95,34 @@ export default defineConfig({
                 autogenerate: { directory: 'getting-started/' },
               },
               {
-                label: 'CONCEPTS',
-                autogenerate: { directory: 'concepts/', collapsed: true },
+                label: 'TUTORIALS',
+                badge: 'NEW!',
+                collapsed: true,
+                items: [
+                  {
+                    label: 'AI Web Scraper',
+                    badge: 'NEW!',
+                    autogenerate: {
+                      directory: 'tutorials/ai-web-scraper/',
+                      collapsed: true,
+                    },
+                  },
+                ],
               },
               {
-                label: 'COMPARISONS',
-                autogenerate: { directory: 'comparisons/', collapsed: true },
+                label: 'HOW TO',
+                collapsed: true,
+                autogenerate: { directory: 'how-to/' },
               },
               {
-                label: 'HOW TO',
-                autogenerate: { directory: 'how-to/', collapsed: true },
+                label: 'CONCEPTS',
+                collapsed: true,
+                autogenerate: { directory: 'concepts/' },
+              },
+              {
+                label: 'COMPARISONS',
+                collapsed: true,
+                autogenerate: { directory: 'comparisons/' },
               },
               {
                 label: 'FAQ - Common Questions',
 
@@ -66,7 +66,7 @@ Before starting, please read the [Install Edge Worker](/edge-worker/getting-star
     (replace `<function-name>` with your function name):
 
     ```bash frame="none"
-    curl http://localhost:54321/functions/v1/<function-name>
+    curl -X POST http://localhost:54321/functions/v1/<function-name>
     ```
 
     This will boot a new instance and start your worker:
 
@@ -81,7 +81,7 @@ serving the request with supabase/functions/greet_user_worker
 In a new terminal, send an HTTP request to start your worker:
 
 ```bash frame="none"
-curl http://localhost:54321/functions/v1/greet_user_worker
+curl -X POST http://localhost:54321/functions/v1/greet_user_worker
 ```
 
 You should see output in your Edge Runtime terminal indicating the worker has started:
@@ -195,10 +195,30 @@ This completes the pgflow getting started guide. You now have all the basics nee
 
 ## Next steps
 
+### Tutorials
+
+Put your pgflow knowledge into practice with hands-on tutorials:
+
+<CardGrid>
+  <LinkCard title="Build an AI Web Scraper" href="/tutorials/ai-web-scraper/" description="Create a workflow that scrapes webpages, analyzes content with OpenAI, and stores results in Postgres"/>
+</CardGrid>
+
+### How-to Guides
+
+Learn essential pgflow techniques:
+
 <CardGrid>
   <LinkCard title="Monitor flow execution" href="/how-to/monitor-flow-execution/" description="Learn how to monitor and observe your pgflow workflow execution in detail"/>
   <LinkCard title="Organize Flows code" href="/how-to/organize-flows-code/" description="Learn how to structure your pgflow code for maintainability and reusability"/>
-  <LinkCard title="Change existing Flow options" href="/how-to/update-flow-options/" description="Learn how to safely update configuration options for existing flows"/>
+  <LinkCard title="Create reusable tasks" href="/how-to/create-reusable-tasks/" description="Build modular tasks that can be shared across multiple workflows"/>
   <LinkCard title="Version your Flows" href="/how-to/version-your-flows/" description="Learn how to safely update your flows without breaking existing runs"/>
+</CardGrid>
+
+### Concepts
+
+Deepen your understanding of pgflow:
+
+<CardGrid>
+  <LinkCard title="How pgflow works" href="/concepts/how-pgflow-works/" description="Understand the core architecture and execution model of pgflow"/>
   <LinkCard title="Understand Flow DSL" href="/concepts/flow-dsl/" description="How pgflow's TypeScript DSL works to create type-safe, data-driven workflows"/>
 </CardGrid>
@@ -0,0 +1,41 @@
+---
+title: Naming workflow steps effectively
+description: Best practices for naming steps in your pgflow flows
+---
+
+Step naming is an important design decision that affects workflow readability and maintainability. After analyzing multiple pgflow projects, these patterns have proven effective.
+
+## Recommended approach: Hybrid naming
+
+- Use **nouns** for steps that produce data other steps depend on
+- Use **verb-noun** combinations for terminal actions or utility steps
+
+```ts
+// Data-producing steps use nouns
+.step({ slug: "website" }, ...)
+.step({ slug: "summary", dependsOn: ["website"] }, ...)
+
+// Terminal action step uses verb-noun
+.step({ slug: "saveToDb", dependsOn: ["summary"] }, ...)
+```
+
+## Why this works well
+
+1. When accessing data from dependent steps, nouns create more intuitive property access:
+   ```ts
+   // Clean and reads naturally
+   ({ website }) => summarizeWithAI(website.content)
+   ```
+
+2. Terminal steps that don't have any dependents benefit from action-oriented naming that clearly describes what they're doing
+
+## Use camelCase for step slugs
+
+```ts
+.step({ slug: "websiteContent" }, ...)   // Correct
+.step({ slug: "website_content" }, ...)  // Avoid
+```
+
+Step slugs are used as identifiers in TypeScript and must match exactly when referenced in dependency arrays. Following JavaScript conventions with camelCase helps maintain consistency.
+
+While this guide recommends the hybrid pattern, the most important thing is consistency within your project. Document the chosen convention and apply it throughout the codebase.