docs(pfweb): website starter sources-sync golden path

[PrzemyslawKlys]

Updates the canonical WebsiteStarter golden path to document SiteSpec Sources + sources-sync workflow (destinations, lock files, and a dev bootstrap command).\n\n- Updates site.json property casing examples (Features/DefaultTheme).\n- Adds copy/paste snippets for site.json Sources and pipeline sources-sync.\n\nTests: dotnet test .\PSPublishModule.sln -c Release

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[claude]

Pull Request Review: PR #121

Summary

This PR enhances the PowerForge.Web.WebsiteStarter.md documentation by:

1. Correcting property casing from camelCase to PascalCase (features → Features, defaultTheme → DefaultTheme)
2. Adding comprehensive documentation for the Sources/sources-sync workflow for multi-repo dependencies

Code Quality: ✅ Excellent

Strengths:

• Clear, well-structured documentation following established patterns
• Comprehensive examples with both site.json and pipeline.json snippets
• Consistent formatting and markdown style
• Proper integration with existing document structure

Documentation Quality: ✅ Strong

What works well:

1. Property casing corrections (lines 15, 34, 35, 137) - Properly aligns with C# PascalCase conventions mentioned in CONTRIBUTING.md
2. Sources section (lines 68-115) - Excellent addition that fills a documentation gap:
   • Clear best practices (lock files, TokenEnv preference, deterministic builds)
   • Helpful explanation of destination/slug behavior
   • Practical code examples for both dev and CI scenarios
   • Good progression from concept → best practices → examples

Minor suggestions:

1. Line 42-43: The inline parenthetical about sources-sync slightly disrupts flow. Consider reformatting:

   - if your site depends on content/projects sourced from other repos:
     - declare them under `Sources` in `site.json`
     - run `sources-sync` before `build` (or use `powerforge-web build --sync-sources` locally)

2. Consistency check: The new section uses "Repo Sources" as the heading, but elsewhere uses "sources-sync" (lowercase, hyphenated). Consider standardizing terminology throughout the document.

Potential Issues: None identified

✅ No bugs detected
✅ No security concerns
✅ No performance implications (documentation only)
✅ Property casing changes align with typed C# models

Test Coverage: ✅ Appropriate

The PR mentions: "Tests: dotnet test .\PSPublishModule.sln -c Release"

This is appropriate for a documentation change. The casing corrections should naturally be validated by:

• Existing JSON schema validation
• Integration tests that parse site.json
• Real usage in the three websites mentioned in AGENTS.md

Recommendations

Optional improvements:

1. Consider adding a migration note if any existing sites use the old camelCase properties:

   **Note:** If upgrading from an older version, update your `site.json`:
   - `features` → `Features`
   - `defaultTheme` → `DefaultTheme`

2. The Sources section could benefit from a brief mention of error handling:

   • What happens if a source repo is unreachable?
   • What happens if lock verification fails?

Questions for clarification:

• Are the old camelCase properties still supported for backward compatibility, or is this a breaking change requiring site updates?
• Should there be a corresponding update to JSON schemas or validation code?

Verdict: ✅ Approve with minor suggestions

This is a high-quality documentation improvement that:

• Fixes a consistency issue (property casing)
• Adds valuable missing documentation (Sources workflow)
• Follows repository conventions
• Includes practical, copy-paste-ready examples

The PR is ready to merge as-is. The suggestions above are truly optional enhancements that could be addressed in follow-up PRs if desired.

---

Review completed by Claude Sonnet 4.5