chore: update documentation and navigation to include starting flows from TypeScript and pgflow client (#257)

## Summary

Simplified and standardized titles across the "Starting Flows" documentation section for better scannability and consistency.

## Changes

### 1\. Simplified Overview Page (`build/starting-flows/index.mdx`)

**Title Changes:**

- Page title: "How to Start Flows" → "Choose your approach"
- Section header: "Detailed Guides on starting flows" → "Detailed Guides"

**Content Improvements:**

- Removed redundant qualifiers ("depending on your needs", "full", "simple")
- Removed 4 repetitive "Quick Example:" labels (structure already implies these are examples)
- Result: 8% word reduction (218 → ~200 words) while maintaining all essential information

**Card Title Simplification:**

- "From TypeScript Client" → "TypeScript Client"
- "With Supabase RPC" → "Supabase RPC"
- "With pg_cron" → "pg_cron"
- "From Database Triggers" → "Database Triggers"

### 2\. Updated Build Index (`build/index.mdx`)

Updated all "Starting Flows" link card titles to match the simplified naming:

- "How to Start Flows" → "Choose your approach"
- "Start Flows from TypeScript Client" → "TypeScript Client"
- "Start Flows with Supabase RPC" → "Supabase RPC"
- "Schedule Flows with pg_cron" → "pg_cron"
- "Trigger Flows on Data Changes" → "Database Triggers"

### 3\. Updated Detail Page Titles

Updated frontmatter titles for autogenerated sidebar consistency:

- `typescript-client.mdx`: "Start Flows from TypeScript Client" → "TypeScript Client"
- `supabase-rpc.mdx`: "Start Flows with Supabase RPC" → "Supabase RPC"
- `pg-cron.mdx`: "Schedule Flows with pg_cron" → "pg_cron"
- `database-triggers.mdx`: "Trigger Flows on Data Changes" → "Database Triggers"

## Benefits

1. **Better Scannability:** Shorter titles are easier to scan in navigation and card grids
2. **Consistency:** Titles now match across overview pages, detail pages, and sidebar
3. **Cleaner Design:** Reduced visual noise makes information hierarchy clearer
4. **MVP Mindset:** Follows the principle of cutting scope and simplifying aggressively

## Testing

- Verified all links remain functional
- Confirmed titles display correctly in sidebar navigation
- Checked that card grids maintain proper layout
- Ensured descriptions still provide sufficient context

Author: jumski

pkgs/client/README.md

@@ -376,5 +376,6 @@ See [BUILD_AND_RELEASE.md](./BUILD_AND_RELEASE.md#browser-via-cdn) for full CDN
 For more detailed documentation, visit:
 
 - [pgflow Documentation](https://pgflow.dev)
-- [Client Library Guide](https://pgflow.dev/how-to/monitor-flow-execution)
+- [Start Flows from TypeScript Client](https://pgflow.dev/build/starting-flows/typescript-client/)
+- [Client API Reference](https://pgflow.dev/reference/pgflow-client/)
 

pkgs/client/project.json

@@ -216,9 +216,7 @@
     },
     "test:types:strict": {
       "executor": "nx:run-commands",
-      "cache": true,
-      "dependsOn": ["build"],
-      "inputs": ["default", "^production"],
+      "dependsOn": ["^build"],
       "options": {
         "cwd": "{projectRoot}",
         "command": "bash ../../scripts/typecheck-ts2578.sh"

pkgs/core/project.json

@@ -285,9 +285,7 @@
     },
     "test:types:strict": {
       "executor": "nx:run-commands",
-      "cache": true,
       "dependsOn": ["^build"],
-      "inputs": ["default", "^production"],
       "options": {
         "cwd": "{projectRoot}",
         "command": "bash ../../scripts/typecheck-ts2578.sh"

pkgs/dsl/project.json

@@ -38,19 +38,15 @@
     },
     "test:types:vitest": {
       "executor": "nx:run-commands",
-      "cache": true,
       "dependsOn": ["build"],
-      "inputs": ["default", "^production"],
       "options": {
         "cwd": "{projectRoot}",
         "command": "pnpm vitest --typecheck.only --run"
       }
     },
     "test:types:strict": {
       "executor": "nx:run-commands",
-      "cache": true,
-      "dependsOn": ["^build"],
-      "inputs": ["default", "^production"],
+      "dependsOn": ["build"],
       "options": {
         "cwd": "{projectRoot}",
         "command": "bash ../../scripts/typecheck-ts2578.sh"

pkgs/website/astro.config.mjs

@@ -168,6 +168,9 @@ export default defineConfig({
     '/concepts/flows/context/': '/concepts/context-object/',
     '/concepts/flows/naming-steps/': '/concepts/naming-steps/',
 
+    // Architecture page rename
+    '/concepts/architecture/': '/concepts/three-layer-architecture/',
+
     // URL Flattening - Reference section
     '/reference/apis/context/': '/reference/context/',
     '/reference/apis/compile-api/': '/reference/compile-api/',
@@ -346,6 +349,10 @@ export default defineConfig({
                     { label: 'Process arrays in parallel', link: '/build/process-arrays-in-parallel/' },
                   ],
                 },
+                {
+                  label: 'Starting Flows',
+                  autogenerate: { directory: 'build/starting-flows/' },
+                },
                 {
                   label: 'Flow Management',
                   items: [
@@ -395,7 +402,7 @@ export default defineConfig({
                   label: 'Architecture',
                   items: [
                     { label: 'How pgflow works', link: '/concepts/how-pgflow-works/' },
-                    { label: 'Architecture', link: '/concepts/architecture/' },
+                    { label: 'Three-layer architecture', link: '/concepts/three-layer-architecture/' },
                     { label: 'Data model', link: '/concepts/data-model/' },
                   ],
                 },
@@ -424,6 +431,7 @@ export default defineConfig({
                 {
                   label: 'APIs',
                   items: [
+                    { label: '@pgflow/client API', link: '/reference/pgflow-client/' },
                     { label: 'Context API', link: '/reference/context/' },
                     { label: 'Compile API', link: '/reference/compile-api/' },
                     { label: 'Manual installation', link: '/reference/manual-installation/' },

pkgs/website/src/assets/cover-images/pgflow-0-7-0-public-beta-map-steps-and-documentation-redesign.png

@@ -5,7 +5,7 @@ description: Learn how to build and author pgflow workflows
 
 import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 
-Now that you've created your first flow, learn how to structure your code, iterate on your flows, and clean up during development.
+Now that you've created your first flow, learn how to structure your code, integrate workflows in applications, and manage your workflows.
 
 ## Writing Flows
 
@@ -32,6 +32,36 @@ Now that you've created your first flow, learn how to structure your code, itera
   />
 </CardGrid>
 
+## Starting Flows
+
+<CardGrid>
+  <LinkCard
+    title="Choose your approach"
+    href="/build/starting-flows/"
+    description="Overview and comparison - choose the right approach for your use case"
+  />
+  <LinkCard
+    title="TypeScript Client"
+    href="/build/starting-flows/typescript-client/"
+    description="Full client library with real-time streaming and event subscriptions"
+  />
+  <LinkCard
+    title="Supabase RPC"
+    href="/build/starting-flows/supabase-rpc/"
+    description="Simple RPC calls for fire-and-forget workflow triggering"
+  />
+  <LinkCard
+    title="pg_cron"
+    href="/build/starting-flows/pg-cron/"
+    description="Run workflows on a recurring schedule with cron expressions"
+  />
+  <LinkCard
+    title="Database Triggers"
+    href="/build/starting-flows/database-triggers/"
+    description="Automatically start workflows when database records change"
+  />
+</CardGrid>
+
 ## Flow Management
 
 <CardGrid>