Add comparisons to DBOS (#117)

* docs: Add information about MCP tools for web reading and crawling to CLAUDE.md

- Updated CLAUDE.md with details on MCP server access and usage
- Included benefits of MCP tools for web content extraction
- Added guidance on quoting special characters in file paths

* docs: add comprehensive documentation comparing pgflow and DBOS workflow systems

- Introduced new documentation file for detailed comparison of pgflow and DBOS
- Included executive summary, feature comparison, and decision guides
- Explained core philosophies, database integration, workflow definition, and deployment
- Highlighted ideal use cases and technical details for both systems
- Summarized similarities in database transaction handling and reliability features

* docs: update comparison documentation to clarify architectural differences and usage scenarios

Refactors the comparison to emphasize the core philosophies of pgflow and DBOS,
including their integration with PostgreSQL, workflow definition approaches,
and deployment environments.
Removes outdated code snippets and technical details,
focusing on high-level distinctions and use cases for better clarity.

* feat: add new documentation page comparing pgflow and Trigger.dev

- Introduces a detailed comparison table of features, architecture, and use cases
- Adds code examples illustrating workflow definitions in both systems
- Summarizes similarities and differences, highlighting integration options with Supabase
- Enhances documentation to assist users in choosing between database-driven and task platform
orchestration

* docs: add comparison documentation between pgflow and Inngest

- Introduces a new MDX file detailing features, use cases, and code examples for both systems
- Highlights architectural differences, integration options, and suitable scenarios
- Provides a comprehensive overview to assist users in choosing the appropriate workflow
orchestration tool

* docs: add explanations overview page with architecture and comparison links

- Introduced new documentation page explaining pgflow's architecture and design
- Added links comparing pgflow to DBOS, Trigger.dev, and Inngest
- Included core concepts and workflow DSL overview for better understanding

* docs: update project naming conventions, development philosophy, and file handling guidance

- Added section on project naming conventions emphasizing lowercase usage
- Clarified MVP status and development priorities
- Updated coding standards to specify camelCase and PascalCase usage
- Included instructions for handling special characters in file paths
- Minor formatting and wording improvements for clarity and consistency

* docs: update PgFlow documentation structure and organization based on Diátaxis framework

- Clarified documentation sections: START HERE, CONCEPTS, HOW IT WORKS, COMPARISONS, HOW TO,
REFERENCE
- Added detailed descriptions for each documentation type and their purpose
- Included guidance on organizing new content and principles for contributing
- Updated project structure overview and emphasized the database-centric approach
- Improved clarity on documentation organization aligning with user needs and technical depth

* docs: add new README documentation for Astro and Starlight project setup and commands

- Introduced a new Markdown file with project structure, usage commands, and resources
- Provided guidance on project organization, asset placement, and command usage
- Included links to external documentation and deployment options
- Marked as a documentation update to improve onboarding and reference materials

* docs: update branding and terminology for pgflow across documentation files

- Standardize references from PgFlow to pgflow in Markdown files
- Correct capitalization in CLI guidance and key principles sections
- Adjust headings and content to reflect consistent naming conventions
- No functional code changes, only documentation updates for clarity and consistency

* docs: add CLAUDE.md documentation guidelines and update README with section details

- Introduced new CLAUDE.md file outlining documentation structure, style, and patterns
- Updated README to replace detailed section descriptions with links to CLAUDE.md and DIATAXIS.md
- Removed redundant documentation section summaries from README for clarity and maintainability

* docs: update website documentation with URL formatting standards and redirect management guidelines

- Added detailed instructions on URL formatting, including trailing slashes and absolute paths
- Included best practices for managing page redirects, including verification, configuration,
and testing
- Clarified when and how to add redirects for page moves, renames, and restructuring
- Enhanced documentation to improve consistency and maintainability of the website

* docs: update redirects, page labels, and rename comparison files for better organization

- Added new redirects for explanations to reorganized concepts and comparisons
- Changed page labels to reflect new section titles and structure
- Renamed comparison MDX files from explanations to dedicated comparisons directory
- Updated links in content to match new file locations and labels
- Reorganized comparison guides and core concepts documentation for clarity

* chore: update documentation structure and add architecture overview

- Collapsed documentation sections for concepts, comparisons, and how-to in config
- Added new architecture overview page with high-level diagram and explanation
- Updated flow DSL documentation to set correct order and clarify data serialization

* docs: add guidelines for redirect management and MDX heading practices

- Updated redirect best practices to emphasize indefinite retention
- Added warning about not using top-level headings in MDX files for documentation

* docs: update documentation to add architecture overview link and improve concept section

* docs: update architecture overview with detailed task flow and mark index as draft

* chore: mark documentation pages as draft to indicate ongoing updates

* docs: remove deprecated architecture overview link from concepts index

Updated the concepts documentation to exclude the outdated architecture overview link,
streamlining the content and focusing on current topics.

Author: jumski

CLAUDE.md

@@ -2,9 +2,22 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## ⚠️ PROJECT NAMING CONVENTION ⚠️
+
+**IMPORTANT**: The name of the project should only ever be used as lowercase: **pgflow**
+
+Never use:
+
+- pgFlow
+- PgFlow
+- Pgflow
+- PGFlow
+
+The only exception is in class names, where "Pgflow" can be used (PascalCase).
+
 ## ⚠️ 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:
+**IMPORTANT**: pgflow is currently a Minimum Viable Product (MVP) in very early stages of development. When working on this codebase:
 
 - **PRIORITIZE CUTTING SCOPE**: Focus on core functionality only - be ruthless about dropping nice-to-have features
 - **SIMPLIFY AGGRESSIVELY**: Choose the simplest implementation that works, not the most elegant or complete
@@ -33,7 +46,7 @@ When suggesting changes or improvements, bias heavily toward solutions that can
 - **Formatting**: Follow existing code style with proper indentation
 - **Testing**: Write tests for both PostgreSQL functions (PgTAP) and TypeScript (Vitest)
 - **Naming**: Use camelCase for variables/functions, PascalCase for classes/types
-- **Error Handling**: Use proper error types and handle errors appropriately 
+- **Error Handling**: Use proper error types and handle errors appropriately
 - **File Structure**: Monorepo structure with packages in pkgs/ directory
 
 ## Packages
@@ -48,6 +61,7 @@ When suggesting changes or improvements, bias heavily toward solutions that can
 ## Architecture & Key Conventions
 
 See [CODEBASE.md](./CODEBASE.md) for:
+
 - High-level architecture (3-layer model: DSL, SQL Core, Edge Worker)
 - Design philosophy (Postgres-first, opinionated, robust yet simple)
 - Key conventions (slug naming, DAG constraints, JSON serialization)
@@ -57,7 +71,15 @@ For documentation structure guidelines based on the Diátaxis framework, see [DI
 
 When working with this codebase, all changes should align with the principles in CODEBASE.md.
 
+## MCP Tools for Web Reading/Crawling
+
+For reading and crawling web content, Claude Code has access to an MCP server that provides enhanced web capabilities:
+
+- **MCP Server**: c4ai-sse at http://localhost:11235/mcp/sse
+- **Usage**: When you need to read web content or crawl websites, use the MCP tools instead of the standard WebFetch
+- **Benefits**: The MCP tools provide more robust capabilities for web content extraction and processing
+
 > [!WARNING]
 > QUOTE ALL THE FILE PATHS THAT CONTAIN SPECIAL CHARACTERS LIKE '[run_id]'
 > BECAUSE BRACKETS HAVE SPECIAL MEANING IN BASH!
-> Do this: `cat 'some/path/to/[id]/page.tsx'` instead of `cat some/path/to/[id]/page.tsx`
+> Do this: `cat 'some/path/to/[id]/page.tsx'` instead of `cat some/path/to/[id]/page.tsx`

DIATAXIS.md

@@ -7,15 +7,15 @@ The [Diátaxis framework](https://diataxis.fr/) provides a systematic approach t
 3. **Explanations** - Understanding-oriented content
 4. **References** - Information-oriented content
 
-## Applying Diátaxis to PgFlow Documentation
+## Applying Diátaxis to pgflow Documentation
 
-PgFlow's documentation can be naturally structured following Diátaxis principles while preserving its unique character and development philosophy.
+pgflow's documentation can be naturally structured following Diátaxis principles while preserving its unique character and development philosophy.
 
 ### Tutorials (Learning-oriented)
 
 Tutorials help new users get started through hands-on experience:
 
-- **Getting Started with PgFlow**
+- **Getting Started with pgflow**
   - First-time setup with Supabase
   - Creating your first workflow with the TypeScript DSL
   - Deploying Edge Workers
@@ -37,7 +37,7 @@ Tutorials should be:
 
 How-to guides address specific tasks for users who know what they need to accomplish:
 
-- **Working with PgFlow**
+- **Working with pgflow**
   - How to deploy to Supabase.com
   - How to implement custom retry logic
   - How to configure worker concurrency
@@ -57,7 +57,7 @@ How-to guides should be:
 
 ### Explanations (Understanding-oriented)
 
-Explanations provide background and context to help users understand PgFlow's concepts:
+Explanations provide background and context to help users understand pgflow's concepts:
 
 - **Core Concepts**
   - The three-layer architecture (DSL, SQL Core, Edge Worker)
@@ -73,7 +73,7 @@ Explanations provide background and context to help users understand PgFlow's co
 
 Explanations should be:
 - Clear about the "why" behind design decisions
-- Connected to PgFlow's design philosophy
+- Connected to pgflow's design philosophy
 - Focused on concepts rather than specific code
 - Providing deeper understanding beyond task completion
 
@@ -115,9 +115,9 @@ Following are some suggestions for organizing the documentation within the exist
    - Generated from code comments where appropriate
    - Reference-style content that's comprehensive and accurate
 
-## Key Principles for PgFlow Documentation
+## Key Principles for pgflow Documentation
 
-While applying Diátaxis, PgFlow documentation should maintain:
+While applying Diátaxis, pgflow documentation should maintain:
 
 1. **Postgres-first mindset** - All explanations should emphasize the database-centric nature
 2. **Three-layer clarity** - Clear separation of DSL, SQL Core, and Edge Worker concepts

NX_README.md

@@ -1,4 +1,4 @@
-# Pgflow
+# pgflow
 
 <a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>
 

pkgs/cli/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Output Philosophy
 
-When designing CLI commands for PgFlow, follow these principles:
+When designing CLI commands for pgflow, follow these principles:
 
 1. **Minimize Output**: Only show information that is directly valuable to the user.
 

pkgs/core/docs/pgflow-blob-reference-system.md

@@ -1,8 +1,8 @@
-# PgFlow Blob Reference System
+# pgflow Blob Reference System
 
 ## Overview
 
-PgFlow needs an efficient way to handle large data outputs from workflow steps. The Blob Reference System provides a solution by separating large data payloads from workflow control information while maintaining a seamless developer experience.
+pgflow needs an efficient way to handle large data outputs from workflow steps. The Blob Reference System provides a solution by separating large data payloads from workflow control information while maintaining a seamless developer experience.
 
 ## How It Works
 
@@ -67,7 +67,7 @@ In this example:
 
 ### Queue Efficiency
 
-A critical optimization in PgFlow is that the task queue only stores minimal task identification information:
+A critical optimization in pgflow is that the task queue only stores minimal task identification information:
 
 - flow_slug
 - run_id
@@ -176,4 +176,4 @@ The developer never needs to:
 
 ## Conclusion
 
-The Blob Reference System in PgFlow provides an elegant solution for handling large data in workflows. By splitting task data into regular inputs and blob references, the system maintains efficient database usage and queue performance while providing a seamless experience for workflow developers. The design ensures that large data is handled appropriately without requiring developers to write special code for blob resolution or storage.
+The Blob Reference System in pgflow provides an elegant solution for handling large data in workflows. By splitting task data into regular inputs and blob references, the system maintains efficient database usage and queue performance while providing a seamless experience for workflow developers. The design ensures that large data is handled appropriately without requiring developers to write special code for blob resolution or storage.

pkgs/dsl/README.md

@@ -1,6 +1,6 @@
 # @pgflow/dsl
 
-The TypeScript Domain Specific Language (DSL) for defining type-safe workflow definitions in PgFlow.
+The TypeScript Domain Specific Language (DSL) for defining type-safe workflow definitions in pgflow.
 
 > [!NOTE]
 > This project and all its components are licensed under [Apache 2.0](./LICENSE) license.
@@ -62,7 +62,7 @@ export const AnalyzeWebsite = new Flow<Input>({
 
 ### Understanding Data Flow
 
-In PgFlow, each step receives an `input` object that contains:
+In pgflow, each step receives an `input` object that contains:
 
 1. **`input.run`** - The original flow input (available to all steps)
 2. **`input.{stepName}`** - Outputs from dependency steps
@@ -96,7 +96,7 @@ const sqlStatements = compileFlow(MyFlow);
 console.log(sqlStatements.join('\n'));
 ```
 
-Alternatively, use the PgFlow CLI to compile flows directly to migration files:
+Alternatively, use the pgflow CLI to compile flows directly to migration files:
 
 ```bash
 npx pgflow compile path/to/flow.ts

pkgs/website/ASTRO_README.md

@@ -0,0 +1,55 @@
+# Astro Documentation Website
+
+This documentation website is built with Astro and Starlight.
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight's docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+
+```
+npm create astro@latest -- --template starlight
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)