feat: monthly ordinal weekday recurrence (1st/last Monday, 2nd Friday, etc.)

- Add first/second/third/fourth/last {Weekday}OfMonth() to ScheduleBuilder
- Add MonthlyOrdinalWeekdayFrequencyConfig for monthly_ordinal_weekday
- Extend SafeFrequencyConfigCast and Model ScheduleBuilder forDate
- Document in README and Boost skills (zap-recurrence, zap-schedules)
- Reorganize README with TOC and clearer recurrence/query sections
- Add unit and feature tests (no regression)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ludoguenet

README.md

@@ -21,6 +21,7 @@ This skill covers all recurrence patterns available in Laravel Zap for creating
 | `everyFiveWeeks` ... `everyFiftyTwoWeeks` | Every N weeks (3-52) |
 | `everyFourMonths` | Every four months |
 | `everyFiveMonths` ... `everyElevenMonths` | Every N months (4, 5, 7-11) |
+| `monthly_ordinal_weekday` | First, second, third, fourth, or last weekday of each month (e.g. `firstWednesdayOfMonth`, `lastMondayOfMonth`) |
 
 ## Daily Recurrence
 
@@ -142,6 +143,41 @@ Zap::for($resource)
     ->save();
 ```
 
+## Monthly Ordinal Weekday (first / second / third / fourth / last X of month)
+
+Recur on the 1st, 2nd, 3rd, 4th, or **last** occurrence of a given weekday each month. Use method names: `first{Day}OfMonth`, `second{Day}OfMonth`, `third{Day}OfMonth`, `fourth{Day}OfMonth`, `last{Day}OfMonth` with any day name (Sunday through Saturday).
+
+```php
+// Every 1st Wednesday of the month
+Zap::for($resource)
+    ->named('Monthly Standup')
+    ->appointment()
+    ->firstWednesdayOfMonth()
+    ->forYear(2025)
+    ->addPeriod('09:00', '10:00')
+    ->save();
+
+// Every 2nd Friday of the month
+Zap::for($resource)
+    ->named('Bi-Monthly Review')
+    ->appointment()
+    ->secondFridayOfMonth()
+    ->forYear(2025)
+    ->addPeriod('14:00', '15:00')
+    ->save();
+
+// Every last Monday of the month
+Zap::for($resource)
+    ->named('Month-End Retro')
+    ->appointment()
+    ->lastMondayOfMonth()
+    ->forYear(2025)
+    ->addPeriod('16:00', '17:00')
+    ->save();
+```
+
+Available methods (replace `{Day}` with Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday): `first{Day}OfMonth`, `second{Day}OfMonth`, `third{Day}OfMonth`, `fourth{Day}OfMonth`, `last{Day}OfMonth`. Examples: `firstWednesdayOfMonth`, `secondFridayOfMonth`, `lastMondayOfMonth`.
+
 ## Bi-Monthly Recurrence
 
 Every two months:
@@ -376,15 +412,24 @@ Zap::for($employee)
 ### Monthly Review Meetings
 
 ```php
-// First Monday of each month (approximate with day 1-7)
+// First Monday of each month (ordinal weekday)
 Zap::for($room)
     ->named('Monthly Review')
     ->appointment()
-    ->monthly(['days_of_month' => [1]])
+    ->firstMondayOfMonth()
     ->forYear(2025)
     ->addPeriod('09:00', '10:00')
     ->withMetadata(['meeting_type' => 'review'])
     ->save();
+
+// Last Friday of each month (month-end review)
+Zap::for($room)
+    ->named('Month-End Review')
+    ->appointment()
+    ->lastFridayOfMonth()
+    ->forYear(2025)
+    ->addPeriod('14:00', '15:00')
+    ->save();
 ```
 
 ## Querying Recurring Schedules

resources/boost/skills/zap-recurrence/SKILL.md

@@ -79,6 +79,8 @@ Zap::for($user)
     ->save();
 ```
 
+Recurrence is set via methods such as `daily()`, `weekly(['monday', 'friday'])`, `monthly(['days_of_month' => [1, 15]])`, and **ordinal weekday**: `firstWednesdayOfMonth()`, `secondFridayOfMonth()`, `lastMondayOfMonth()` (see zap-recurrence skill for all patterns).
+
 ## Date Range Methods
 
 ```php

resources/boost/skills/zap-schedules/SKILL.md

@@ -13,6 +13,7 @@
 use Zap\Data\MonthlyFrequencyConfig\BiMonthlyFrequencyConfig;
 use Zap\Data\MonthlyFrequencyConfig\EveryXMonthsFrequencyConfig;
 use Zap\Data\MonthlyFrequencyConfig\MonthlyFrequencyConfig;
+use Zap\Data\MonthlyFrequencyConfig\MonthlyOrdinalWeekdayFrequencyConfig;
 use Zap\Data\MonthlyFrequencyConfig\QuarterlyFrequencyConfig;
 use Zap\Data\MonthlyFrequencyConfig\SemiAnnuallyFrequencyConfig;
 use Zap\Data\WeeklyFrequencyConfig\BiWeeklyFrequencyConfig;
@@ -80,6 +81,41 @@
  * @method self everyNineMonths(array $config = [])
  * @method self everyTenMonths(array $config = [])
  * @method self everyElevenMonths(array $config = [])
+ * @method self firstSundayOfMonth()
+ * @method self firstMondayOfMonth()
+ * @method self firstTuesdayOfMonth()
+ * @method self firstWednesdayOfMonth()
+ * @method self firstThursdayOfMonth()
+ * @method self firstFridayOfMonth()
+ * @method self firstSaturdayOfMonth()
+ * @method self secondSundayOfMonth()
+ * @method self secondMondayOfMonth()
+ * @method self secondTuesdayOfMonth()
+ * @method self secondWednesdayOfMonth()
+ * @method self secondThursdayOfMonth()
+ * @method self secondFridayOfMonth()
+ * @method self secondSaturdayOfMonth()
+ * @method self thirdSundayOfMonth()
+ * @method self thirdMondayOfMonth()
+ * @method self thirdTuesdayOfMonth()
+ * @method self thirdWednesdayOfMonth()
+ * @method self thirdThursdayOfMonth()
+ * @method self thirdFridayOfMonth()
+ * @method self thirdSaturdayOfMonth()
+ * @method self fourthSundayOfMonth()
+ * @method self fourthMondayOfMonth()
+ * @method self fourthTuesdayOfMonth()
+ * @method self fourthWednesdayOfMonth()
+ * @method self fourthThursdayOfMonth()
+ * @method self fourthFridayOfMonth()
+ * @method self fourthSaturdayOfMonth()
+ * @method self lastSundayOfMonth()
+ * @method self lastMondayOfMonth()
+ * @method self lastTuesdayOfMonth()
+ * @method self lastWednesdayOfMonth()
+ * @method self lastThursdayOfMonth()
+ * @method self lastFridayOfMonth()
+ * @method self lastSaturdayOfMonth()
  */
 class ScheduleBuilder
 {
@@ -673,13 +709,20 @@ public function clone(): self
     /**
      * Handle dynamic method calls for everyXWeeks and everyXMonths patterns.
      *
-     * @param  string  $method
      * @param  array<int, mixed>  $parameters
      *
      * @throws BadMethodCallException
      */
     public function __call(string $method, array $parameters): self
     {
+        // Match ordinal weekday of month: firstWednesdayOfMonth, secondFridayOfMonth, lastMondayOfMonth
+        if (preg_match('/^(first|second|third|fourth|last)(Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday)OfMonth$/i', $method, $ordinalMatches)) {
+            return $this->setMonthlyOrdinalWeekdayFrequency(
+                $ordinalMatches[1],
+                $ordinalMatches[2]
+            );
+        }
+
         // Match patterns like everyThreeWeeks, everyFourMonths, etc.
         if (preg_match('/^every([A-Z][a-zA-Z]+)(Week|Weeks|Month|Months)$/', $method, $matches)) {
             $wordNumber = $matches[1];
@@ -765,8 +808,6 @@ private function wordToNumber(string $word): ?int
      * Set schedule to recur every X weeks.
      *
      * @param  int<1, 52>  $weeks
-     * @param  array  $days
-     * @param  CarbonInterface|string|null  $startsOn
      */
     private function setEveryXWeeksFrequency(int $weeks, array $days, CarbonInterface|string|null $startsOn): self
     {
@@ -781,11 +822,48 @@ private function setEveryXWeeksFrequency(int $weeks, array $days, CarbonInterfac
         return $this;
     }
 
+    /**
+     * Set schedule to recur on an ordinal weekday of each month (e.g. 1st Wednesday, last Monday).
+     *
+     * @param  string  $ordinalWord  first, second, third, fourth, last
+     * @param  string  $dayName  Sunday, Monday, ... Saturday
+     */
+    private function setMonthlyOrdinalWeekdayFrequency(string $ordinalWord, string $dayName): self
+    {
+        $ordinal = match (strtolower($ordinalWord)) {
+            'first' => 1,
+            'second' => 2,
+            'third' => 3,
+            'fourth' => 4,
+            'last' => 5,
+            default => throw new BadMethodCallException("Invalid ordinal '{$ordinalWord}' in method."),
+        };
+
+        $dayOfWeek = match (strtolower($dayName)) {
+            'sunday' => 0,
+            'monday' => 1,
+            'tuesday' => 2,
+            'wednesday' => 3,
+            'thursday' => 4,
+            'friday' => 5,
+            'saturday' => 6,
+            default => 1,
+        };
+
+        $this->attributes['is_recurring'] = true;
+        $this->attributes['frequency'] = 'monthly_ordinal_weekday';
+        $this->attributes['frequency_config'] = new MonthlyOrdinalWeekdayFrequencyConfig(
+            ordinal: $ordinal,
+            dayOfWeek: $dayOfWeek,
+        );
+
+        return $this;
+    }
+
     /**
      * Set schedule to recur every X months.
      *
      * @param  int<1, 12>  $months
-     * @param  array  $config
      */
     private function setEveryXMonthsFrequency(int $months, array $config): self
     {

src/Builders/ScheduleBuilder.php

@@ -6,6 +6,7 @@
 use Illuminate\Database\Eloquent\Model;
 use Zap\Data\FrequencyConfig;
 use Zap\Data\MonthlyFrequencyConfig\EveryXMonthsFrequencyConfig;
+use Zap\Data\MonthlyFrequencyConfig\MonthlyOrdinalWeekdayFrequencyConfig;
 use Zap\Data\WeeklyFrequencyConfig\EveryXWeeksFrequencyConfig;
 use Zap\Models\Schedule;
 
@@ -38,6 +39,11 @@ public function get(Model $model, string $key, mixed $value, array $attributes)
                 );
             }
 
+            // Handle monthly ordinal weekday (e.g., "first Wednesday of month")
+            if ($frequency === 'monthly_ordinal_weekday') {
+                return MonthlyOrdinalWeekdayFrequencyConfig::fromArray($configArray);
+            }
+
             return $configArray;
         }