chore: update and reorganize redirects for historical, main branch, and concept paths (#262)

- Added and refined redirects for historical URLs, including old get-started, edge-worker,
and FAQ paths
- Moved main branch paths from 'getting-started' to 'get-started' and from 'vs' to 'comparisons'
- Updated redirects for concepts, build, deploy, and reference sections to reflect new structure
- Included redirects for old architecture, explanations, and news articles to current locations
- Overall, improved URL consistency and maintained backward compatibility across documentation

Author: jumski

.claude/commands/audit-doc.md

@@ -1,142 +1,183 @@
+---
+allowed-tools: Read, Grep, Bash(ls:*), Bash(tree:*), Bash(wc -l:*)
+description: Audit documentation files for compliance with pgflow guidelines and Diataxis
+argument-hint: <file-path>
+---
+
 You are tasked with auditing documentation for compliance with pgflow guidelines, Diataxis framework, and identifying quality issues.
 
 ## Context
 
 Documentation root: `pkgs/website/src/content/docs/`
 
-Target for audit:
-<target>
+User request:
+<request>
 $ARGUMENTS
-</target>
+</request>
 
-## Process
+## Multi-Step Process
 
 ### Step 1: Validate Target
 
 **Target must be a single .mdx file path.**
 
 If no argument or directory provided:
-- Ask user to specify a single file path
-- Example: `/audit-doc guides/getting-started.mdx`
+- Search for matching files using Grep/tree
+- Present options to user
+- WAIT for confirmation
 
-Present target file and **WAIT for confirmation.**
+If path provided, verify file exists:
+```bash
+ls -la pkgs/website/src/content/docs/[file-path]
+```
 
-### Step 2: Determine Audit Mode
+Present target:
+```markdown
+## Audit Target
 
-Ask user which audit mode:
-- **Quick**: Diataxis + critical style issues only
-- **Standard**: All categories, standard depth (default)
-- **Deep**: Comprehensive review with detailed analysis
+**File:** pkgs/website/src/content/docs/[path]
+**Lines:** [count]
+```
 
-### Step 3: Perform Audit with Task Agent
+WAIT for user confirmation.
 
-**Launch a single general-purpose task agent to audit the file.**
+### Step 2: Read Guide Files
 
-Present the task summary to the user before launching:
+Read all guide files to understand standards:
 
-```markdown
-## Task Agent Instructions
-
-I'm launching a task agent to audit the documentation with these instructions:
-
-**Context:**
-- Target file: [filepath]
-- Audit mode: [Quick/Standard/Deep]
-
-**Agent will:**
-1. Read NOMENCLATURE_GUIDE.md for terminology standards
-2. Read ARCHITECTURE_GUIDE.md for architectural accuracy
-3. Read DOCS_GUIDE.md for compliance criteria, patterns, and examples
-4. Read .claude/character_guidelines.md for character rules
-5. Read .claude/diataxis.md for content type definitions
-6. Read .claude/naming_convention.md for naming rules
-7. Audit the file against all standards
-8. Generate structured report with specific examples and priorities
-
-**Audit categories to check (BE PRAGMATIC, NOT PEDANTIC):**
-1. **Critical Issues Only** - Broken links, wrong code, incorrect architecture/terminology, character violations
-2. **Style Compliance** - pgflow naming (not pgFlow/PgFlow), voice consistency, trailing slashes
-3. **Structural Issues** - Missing frontmatter, H1 usage, broken code examples
-4. **Content Quality** - Technical accuracy, missing important info, unclear explanations
-
-**IMPORTANT - DO NOT flag these as issues:**
-- Missing contentType in frontmatter (we don't use it)
-- Mixing installation/setup with how-to content (pragmatic for small sections)
-- Missing "What You'll Learn" sections (only needed for long/complex docs)
-- Platform-specific notes when only one platform exists (Supabase is the only platform currently)
-- Small docs that don't need splitting (<400 lines is fine)
-
-**BE PRAGMATIC:**
-- Content type mixing is OK if it serves the user (brief install section in how-to is fine)
-- Suggest reorganization ONLY if specific, actionable, and clearly better
-- Don't invent requirements not in the guides
-
-**Report format:**
+```bash
+# Read guides in parallel
+```
+
+Files to read:
+1. `NOMENCLATURE_GUIDE.md` - Terminology standards
+2. `ARCHITECTURE_GUIDE.md` - Architecture concepts
+3. `DOCS_GUIDE.md` - Documentation standards
+4. `.claude/core/character_guidelines.md` - Character rules
+5. `.claude/core/diataxis.md` - Content type definitions
+6. `.claude/core/naming_convention.md` - Naming rules
+
+### Step 3: Read Target File
+
+Read the target documentation file completely.
+
+### Step 4: Analyze Against Standards
+
+**BE PRAGMATIC**: Only flag issues that significantly impact readers or correctness. Don't be nitpicky about things that mostly work.
+
+**Critical Issues - Must fix:**
+- Broken links (internal/external)
+- Wrong/broken code examples
+- Incorrect architecture/terminology
+- Character violations (curly quotes, em-dashes, etc.)
+- Incorrect naming (pgFlow, PgFlow, etc.)
+
+**Important Issues - Should fix:**
+- Missing trailing slashes on internal links
+- Missing or incorrect frontmatter
+- Wrong H1 usage (multiple H1s in content)
+- Significantly unclear explanations
+
+**Only if valuable to readers:**
+- Suggest Diataxis improvements ONLY if doc is clearly misclassified
+- Suggest reorganization ONLY if current structure causes confusion
+- Suggest cross-references ONLY if missing links hurt understanding
+
+**DO NOT flag:**
+- Minor style inconsistencies
+- Content type mixing if it serves users (brief install in how-to is fine)
+- Small docs (<400 lines)
+- Missing "What You'll Learn" sections
+- Platform notes when only one platform exists
+
+### Step 5: Generate Report
+
+Create a structured report with specific examples:
 
 ```markdown
 # Audit Report: [filename]
-**Location:** [path]
+
+**Location:** pkgs/website/src/content/docs/[path]
 **Type:** [Tutorial/How-to/Explanation/Reference]
-**Length:** [count] lines
+**Lines:** [count]
 
-## Tier A: CRITICAL ISSUES
-[Diataxis violations, broken links, incorrect code, terminology violations, architectural inaccuracies]
+## Critical Issues
 
-A1. [Issue description with line numbers and specific examples]
-A2. [Issue description with line numbers and specific examples]
-...
+[If none: "None found"]
+[If found: List with line numbers and examples]
 
-## Tier B: IMPORTANT ISSUES
-[Style violations, structural problems, naming inconsistencies]
+1. [Issue] (line [X])
+   - Found: `[actual text]`
+   - Fix: `[suggested text]`
 
-B1. [Issue description with line numbers and specific examples]
-B2. [Issue description with line numbers and specific examples]
-...
+2. [Issue] (lines [X-Y])
+   - Problem: [description]
+   - Suggestion: [fix]
 
-## Tier C: IMPROVEMENTS
-[Content quality, cross-references, clarity enhancements]
+## Important Issues
 
-C1. [Issue description with line numbers and specific examples]
-C2. [Issue description with line numbers and specific examples]
-...
+[Similar format]
 
-## SUMMARY
-**Assessment:** [Excellent/Good/Needs Work/Major Issues]
-**Priority Actions:** [Top 3 fixes using tier notation, e.g., "A1, A3, B2"]
-**Estimated Effort:** [Small/Medium/Large]
-```
+## Suggestions
 
-**Instructions for agent:**
-- Number each issue within its tier (A1, A2, A3... B1, B2, B3... C1, C2, C3...)
-- Provide line numbers and specific examples for each issue
-- Be constructive with suggested fixes
-- Prioritize critical issues first
-- Suggest next commands to run using tier notation (e.g., "fix A1,2,3 and B1")
-```
+[Only significant improvements that add real value]
 
-**Launching agent...**
+## Summary
 
-Use the Task tool with subagent_type "general-purpose" and provide:
-- Target file path and audit mode
-- Instructions to read all guide files (NOMENCLATURE_GUIDE.md, ARCHITECTURE_GUIDE.md, DOCS_GUIDE.md, .claude/character_guidelines.md, .claude/diataxis.md, .claude/naming_convention.md)
-- Report format specified above
-- Instructions to provide specific examples and line numbers
+**Assessment:** [Excellent/Good/Needs Work/Major Issues]
+**Critical:** [count] | **Important:** [count] | **Suggestions:** [count]
+**Estimated fix time:** [5min/15min/30min/1hr]
+
+**Next steps:**
+1. [Most important fix]
+2. [Second priority]
+3. [Third priority if any]
+```
 
-## Output Format
+### Step 6: Present Findings
 
-After the task agent completes, present results to the user:
+Show the report to the user with actionable next steps:
 
 ```markdown
-## Audit Complete: [filename]
+## Audit Complete
 
-**Tier A (Critical) issues:** [count]
-**Tier B (Important) issues:** [count]
-**Tier C (Improvements):** [count]
-**Overall assessment:** [summary]
+[Show the report]
 
 **Next steps:**
-- Review the detailed report above
-- You can now reference issues by tier notation (e.g., "fix A1,2,3 and B2")
-- Fix Tier A issues first, then B, then C
-- Consider splitting if document is >300 lines
+- Fix critical issues first
+- You can say "fix issue 1 and 3" to address specific items
+- Run `/audit-doc [file]` again after fixes to verify
 ```
+
+## Common Issues Reference
+
+**Critical (always fix):**
+- `pgFlow`/`PgFlow` → `pgflow`
+- `/path/to/doc` → `/path/to/doc/` (trailing slash)
+- Curly quotes "" → Straight quotes ""
+- Em-dash — → Hyphen -
+- Broken code examples
+
+**Important (fix if found):**
+- Multiple H1s → Only one H1 in frontmatter title
+- Missing `draft: false` in frontmatter
+- Code blocks without language
+- Relative links `../other` → Absolute `/other/`
+
+**Suggestions (only if valuable):**
+- Missing cross-references that would help understanding
+- Structure issues causing real confusion
+- Diataxis misclassification (e.g., tutorial written as reference)
+
+## Error Handling
+
+- **File not found:** Ask user to verify path
+- **Not .mdx file:** Only audit .mdx files
+- **Too large (>1000 lines):** Warn and suggest splitting first
+
+## Special Cases
+
+- **index.mdx:** Check for proper overview structure
+- **Tutorial:** Verify step-by-step progression
+- **Reference:** Check completeness and accuracy
+- **How-to:** Verify problem-solving focus