tweaks to docs here and there (#97)

* fix: update import syntax, remove deprecated code, and clarify documentation

Refactors import statements to use default imports, removes unused simulateFailure step,
and updates instructions for consistency.
Also corrects minor formatting issues in docs.

* fix(docs): correct installation prerequisites and remove redundant content

Update the documentation to fix a typo in the create-first-flow guide, and revise the prerequisites
in the install-pgflow guide by specifying the correct Deno version.

* feat: update flow and task files for greeting workflow and rename related components

Refactors the example to create a greeting flow instead of website analysis, including
modifying flow definitions, task implementations, and worker setup for the new flow.
Also updates migration and documentation to reflect the new greeting workflow.

* docs: update documentation to mark page as draft and clarify structure guidance

- Set the page as a draft to prevent premature publication
- Slight wording adjustment for clarity in the introduction
- Corrected a minor formatting issue at the end of the file

* refactor: update flow step names and references for consistency in documentation

- Renamed 'format_name' step to 'full_name' in SQL, flow definition, and documentation
- Updated corresponding references and output examples across multiple files
- Minor formatting adjustments for clarity and consistency in the tutorials and SQL snippets

* feat: add website analysis workflow and update documentation

- Introduced a new code example demonstrating a website analysis flow with scraping, summarization,
and tagging steps
- Updated documentation to correct typo in tagline and improve clarity of workflow orchestration
examples
- Refactored existing workflow code to include the new analyze_website flow, replacing previous
placeholder
- Minor formatting and consistency improvements across code and docs

* docs: update tutorial content, improve structure, and clarify installation steps

- Revised 'create-first-flow' MDX to update example workflow description and add step details
- Enhanced readability by adjusting formatting and removing deprecated sections
- Clarified 'install-pgflow' instructions with a new 'What was installed?' section
- Removed outdated navigation links from index page for better clarity and accuracy

* docs: update documentation to remove NotProductionReady component and improve flow creation
instructions

- Removed deprecated NotProductionReady component from compile-to-sql.md
- Clarified steps for compiling, examining, and applying SQL migrations
- Changed note styling from Aside to note for better emphasis
- Minor formatting adjustments for clarity and consistency

* docs: add new guide on versioning flows and remove deprecated flow management warnings

- Introduced a new documentation page detailing safe flow versioning strategies
- Removed outdated caution and danger sections from existing flow compilation docs
- Updated content to include best practices for managing flow migrations and updates
- Ensured consistency across documentation regarding flow versioning and modification guidelines

* docs: update documentation to remove aside in compile-to-sql and clarify flow creation steps

- Removed deprecated aside note in compile-to-sql.md
- Clarified project structure and flow creation instructions in create-first-flow.md
- Improved explanations of flow features and key concepts for better understanding

* chore(docs): update manual installation instructions for migration files, environment setup,
and runtime policy

- Clarify steps to download, extract, and copy migration files
- Add instructions for creating environment variables with proper URL encoding
- Include configuration changes for connection pooling and Edge Runtime policy
- Update restart commands to reflect the latest setup process

* docs: update prerequisite requirements in getting started guide

- Clarify that Deno version 1.45.x or higher is required before compiling flows to SQL

* docs: add NotProductionReady component to multiple docs and remove redundant import

* docs: remove draft status from organize-flows-codebase documentation

Author: jumski

pkgs/website/src/code-examples/analyze_website_simplified.ts.raw

@@ -0,0 +1,25 @@
+new Flow<{ url: string }>({
+  slug: 'analyze_website',
+})
+  .step(
+    { slug: 'website' },
+    async (input) => await scrapeWebsite(input.run.url)
+  )
+  .step(
+    { slug: 'summary', dependsOn: ['website'] },
+    async (input) => await summarizeWithAI(input.website.content)
+  )
+  .step(
+    { slug: 'tags', dependsOn: ['website'] },
+    async ({}) => await extractTags(input.website.content)
+  )
+  .step(
+    { slug: 'saveToDb', dependsOn: ['summary', 'tags'] },
+    async ({ run, summary, tags }) =>
+      await saveWebsite({
+        user_id: run.user_id,
+        website_url: run.url,
+        summary,
+        tags,
+      })
+  );

pkgs/website/src/content/docs/getting-started/compile-to-sql.mdx

@@ -10,7 +10,7 @@ import NotProductionReady from '@/components/NotProductionReady.astro';
 
 Now that we've defined our flow, we need to register it in the database. pgflow provides a CLI tool that compiles your TypeScript flow definition into SQL migrations that can be applied to your Supabase database.
 
-<NotProductionReady />
+<NotProductionReady/>
 
 ## What is compilation?
 
@@ -27,163 +27,66 @@ This is an essential step because pgflow's runtime executes flows based on their
 Before continuing, make sure you have:
 - Completed the [flow definition](/getting-started/create-first-flow/) from the previous step
 - The Supabase CLI installed and configured
+- Deno version 1.45.x or higher
 </Aside>
 
-<Steps>
-1. ### Compile the flow to SQL
+### 1. Compile the flow to SQL
 
-    Run the pgflow compile command, pointing to your flow definition file:
+Run the pgflow compile command, pointing to your flow definition file:
 
-    ```bash frame="none"
-    npx pgflow@latest compile supabase/functions/_flows/analyze_website.ts
-    ```
-
-    This will:
-    - Parse your TypeScript flow definition
-    - Extract the flow structure, step dependencies, and configuration
-    - Generate SQL commands to register the flow in the database
-    - Create a timestamped migration file in your Supabase migrations folder
-
-    You should see output like this:
-
-    ```
-    ✓ Successfully compiled flow to SQL
-    ✓ Migration file created: supabase/migrations/20250505120000_create_analyze_website_flow.sql
-    ```
-
-2. ### Examine the generated SQL
-
-    Let's look at what got generated. Open the migration file in your editor:
-
-    ```bash frame="none"
-    cat supabase/migrations/20250505120000_create_analyze_website_flow.sql
-    ```
-
-    The migration file contains SQL commands that:
-    
-    1. Create the flow definition
-    2. Add each step with its configuration
-    3. Define dependencies between steps
-
-    Here's a simplified view of what the SQL looks like:
-
-    ```sql
-    -- Create the flow
-    SELECT pgflow.create_flow('analyze_website', max_attempts => 3, base_delay => 1, timeout => 4);
-
-    -- Add steps and define their dependencies
-    SELECT pgflow.add_step('analyze_website', 'website');
-    SELECT pgflow.add_step('analyze_website', 'summary', ARRAY['website']);
-    SELECT pgflow.add_step('analyze_website', 'tags', ARRAY['website']);
-    SELECT pgflow.add_step('analyze_website', 'saveToDb', ARRAY['summary', 'tags']);
-    ```
-
-    This SQL representation is what the pgflow runtime system uses to execute your workflow.
-
-3. ### Apply the migration
-
-    Now that we have the SQL migration, we need to apply it to our database:
-
-    ```bash frame="none"
-    npx supabase migrations up
-    ```
-
-    This will execute the SQL migration and register your flow definition in the database.
-
-    If successful, you should see output like:
-
-    ```
-    Applying migration 20250505120000_create_analyze_website_flow.sql...done
-    ```
-
-</Steps>
+```bash frame="none"
+npx pgflow@latest compile supabase/functions/_flows/greet_user.ts
+```
 
-## Managing flow changes and versioning
+This will:
+- Parse your TypeScript flow definition
+- Extract the flow structure, step dependencies, and configuration
+- Generate SQL commands to register the flow in the database
+- Create a timestamped migration file in your Supabase migrations folder
 
-:::caution[Current Compilation Limitations]
-**Important:** The current version of pgflow's compiler:
+You should see output like this:
 
-1. Always creates a **new migration file** for any changes
-2. Does not provide automatic update functionality for existing flows
-3. Cannot safely change step dependencies or flow structure
+```
+✓ Successfully compiled flow to SQL
+✓ Migration file created: supabase/migrations/20250505120000_create_greet_user_flow.sql
+```
 
-For any changes to an existing flow, you must:
-- Manually handle migration files
-- **NEVER** change dependencies, step slugs, or flow structure in existing flows
-- For non-breaking changes, manually update using SQL commands
-:::
+### 2. Examine the generated SQL
 
-:::danger[Prohibited Changes]
-DO NOT attempt to change these aspects of an existing flow:
-- Step slugs
-- Dependencies between steps
-- Adding or removing steps
-- Altering the flow's input type structure
+Let's look at what got generated. Open the migration file in your editor:
 
-These changes will break in-progress runs and cause data compatibility issues.
-:::
+```bash frame="none"
+cat supabase/migrations/20250505120000_create_greet_user_flow.sql
+```
 
-### Version management strategy
+The migration file contains SQL commands that:
 
-pgflow uses the flow's `slug` as its identifier, so to create a new version:
+1. Create the flow definition
+2. Add each step with its configuration
+3. Define dependencies between steps
 
-1. **Create a new flow definition file** with a versioned slug (e.g., `analyze_website_v2.ts`)
-2. **Manually manage migration files**:
-   - Keep previous migration files for existing runs
-   - Create new migrations for the new flow version
+The generated SQL looks like this:
 
-```typescript
-// analyze_website_v2.ts
-export default new Flow<Input>({
-  slug: 'analyze_website_v2',  // Note the versioned slug
-  // ...configuration
-})
+```sql
+SELECT pgflow.create_flow('greet_user');
+SELECT pgflow.add_step('greet_user', 'full_name');
+SELECT pgflow.add_step('greet_user', 'greeting', ARRAY['full_name']);
 ```
 
-### Safe vs. breaking changes
-
-| Safe Changes | Breaking Changes |
-| ------------ | --------------- |
-| Modifying step implementation | Adding/removing steps |
-| Adjusting retry parameters | Changing step dependencies |
-| Updating timeout values | Modifying input/output types |
-| Bug fixes within steps | Changing step slug names |
+This SQL representation is what the pgflow runtime system uses to execute your workflow.
 
-### Updating non-breaking configuration options
+### 3. Apply the migration
 
-For non-breaking changes like adjusting retry settings or timeouts, you must manually update the database with SQL commands.
+Now that we have the SQL migration, we need to apply it to our database:
 
-:::tip[How To Guide]
-We've created a detailed guide on [how to update flow options](/how-to/update-flow-options/) that covers:
-- All available configuration options
-- SQL commands for updating flows and steps
-- Best practices for maintaining compatibility
-
-For any non-breaking changes to existing flows, refer to this guide rather than recompiling.
-:::
-
-### Task reusability
+```bash frame="none"
+npx supabase migrations up
+```
 
-The separation of tasks from flows helps with versioning:
+This will execute the SQL migration and register your flow definition in the database.
 
-- Tasks can be reused across multiple flow versions
-- Implementation details can evolve independently of flow structure
-- New flow versions can reuse existing task implementations
+If successful, you should see output like:
 
-```typescript
-// Both flow versions can use the same task implementations
-// analyze_website_v1.ts and analyze_website_v2.ts
-import { scrapeWebsite } from '../_tasks/scrapeWebsite.ts';
 ```
-
-:::note[Flow Versioning Tips]
-- For non-breaking configuration changes: Update database directly with SQL
-- For breaking changes: Always create a new flow with a versioned slug
-- Consider a versioning scheme (v1, v2, etc.) for your flow slugs
-- Always test migrations thoroughly before applying in production
-- Plan how to migrate in-progress runs when deploying new versions
-:::
-
-<Aside>
-Now that your flow is registered in the database, the next step is to [set up a worker and trigger the flow](/getting-started/trigger-and-monitor/).
-</Aside>
+Applying migration 20250505120000_create_greet_user_flow.sql...done
+```