===============
LIBRARY RULES
===============
From library maintainers:
- Seat counts are the top of the published ranges: SuperCoach 57, Coach Bus 44, Small Coach Bus 28, Executive Sprinter Van 15, Party Bus 45, Trolley 30.
- The planners are estimates, not quotes, bookings or availability statements.
- recommend_fleet returns the fewest vehicles and then the fewest spare seats.

### CharterPlanner usage example

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/nuget/README.md

Shows how to use the CharterPlanner class to calculate headcount with buffer, recommend a fleet, and get vehicles needed. The example outputs a summary and a count for SuperCoach vehicles.

```csharp
using ChicagoCharterBusRental;

var headcount = CharterPlanner.HeadcountWithBuffer(80);   // 84, +5% for late additions
var plan = CharterPlanner.RecommendFleet(headcount);
Console.WriteLine(plan.Summary);
// 1 x SuperCoach (50-57 seats) + 1 x Small Coach Bus (22-28 seats)
// = 85 seats for 84 passengers, 1 spare

Console.WriteLine(CharterPlanner.VehiclesNeeded(headcount, Vehicle.SuperCoach)); // 2
```

--------------------------------

### Fleet Planning Example with Resources and Vehicle

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/packagist/README.md

Shows how to use Resources::headcountWithBuffer, recommendFleet, and vehiclesNeeded to plan a fleet for a given headcount. The example adds a 5% buffer, recommends a fleet, prints a summary, and calculates vehicles needed for a specific vehicle class.

```php
use ChicagoSuperCoach\CharterBusRental\Resources;
use ChicagoSuperCoach\CharterBusRental\Vehicle;

$headcount = Resources::headcountWithBuffer(80);   // 84, +5% for late additions
$plan = Resources::recommendFleet($headcount);
echo $plan->summary();
// 1 x SuperCoach (50-57 seats) + 1 x Small Coach Bus (22-28 seats)
// = 85 seats for 84 passengers, 1 spare

echo Resources::vehiclesNeeded($headcount, Vehicle::SuperCoach); // 2
```

--------------------------------

### Usage example for fleet planning functions

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/pub_dev/README.md

Shows how to import the package, add a 5% buffer to a headcount, recommend a fleet, and get the number of vehicles needed for a specific class. The output demonstrates the recommended fleet summary and the vehiclesNeeded result. All functions throw ArgumentError for a headcount below 1.

```dart
import 'package:chicago_charter_bus_rental/chicago_charter_bus_rental.dart';

void main() {
  // 80 confirmed guests plus a 5% buffer for late additions.
  final headcount = headcountWithBuffer(80); // 84
  final plan = recommendFleet(headcount);
  print(plan.summary);
  // 1 x SuperCoach (50-57 seats) + 1 x Small Coach Bus (22-28 seats)
  // = 85 seats for 84 passengers, 1 spare

  print(vehiclesNeeded(headcount, CharterVehicle.superCoach)); // 2
}
```

--------------------------------

### Run fleet_plan.py for vehicle recommendation

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/smithery-ai/chicago-group-travel/SKILL.md

Use the bundled script to get an exact vehicle recommendation based on headcount. The --buffer flag adds a percentage buffer for late additions, and --all includes party bus and trolley options. Output is an estimate and must be confirmed with the provider.

```bash
python3 scripts/fleet_plan.py 84            # 1 x SuperCoach + 1 x Small Coach Bus
python3 scripts/fleet_plan.py 80 --buffer 5 # plans for 84
python3 scripts/fleet_plan.py 45 --all      # include party bus and trolley
```

--------------------------------

### Ruby usage example for chicago_charter_bus_rental

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/rubygems/README.md

Shows how to require the gem, compute a headcount with a 5% buffer, recommend a fleet, and get the number of vehicles needed for a specific class. The output demonstrates the summary format and the result of vehicles_needed for a SuperCoach.

```ruby
require "chicago_charter_bus_rental"

headcount = ChicagoCharterBusRental.headcount_with_buffer(80) # 84, +5% for late additions
plan = ChicagoCharterBusRental.recommend_fleet(headcount)
puts plan.summary
# 1 x SuperCoach (50-57 seats) + 1 x Small Coach Bus (22-28 seats)
# = 85 seats for 84 passengers, 1 spare

ChicagoCharterBusRental.vehicles_needed(headcount, ChicagoCharterBusRental::SUPER_COACH) # 2
```

--------------------------------

### Publish with python -m build and twine upload

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/pypi/README.md

Build the package and upload to PyPI. Run in the project root after installing build and twine.

```bash
python -m build && twine upload dist/*
```

--------------------------------

### Import and use chicago_charter_bus_rental

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/pypi/README.md

Import the package and print its title and homepage URL. Requires the package to be installed.

```python
import chicago_charter_bus_rental as ccb

print(ccb.TITLE, ccb.homepage())
```

--------------------------------

### Run Travel Pal with flutter pub get and flutter run

Source: https://github.com/nbkdevs/chicago-super/blob/main/README.md

Use these commands to fetch dependencies and launch the Flutter app. Run them in the project root after cloning the repository.

```bash
flutter pub get
flutter run
```

--------------------------------

### Travel Pal trip memory with transportation

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/smithery-ai/chicago-group-travel/SKILL.md

Example YAML structure for recording a trip memory in Travel Pal, including transportation details. Transportation is recorded as contextual information within the trip memory, not as the primary purpose.

```yaml
memory:
  title: Architecture Cruise
  date: 2026-09-20
  location: Chicago River
  tags:
    - chicago
    - sightseeing
    - architecture

transportation:
  pickup: Downtown Chicago
  destination: Chicago River
  notes: Group transportation arranged for the afternoon.
```

--------------------------------

### Run Tests with php tests/run.php

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/packagist/README.md

Command to run the test suite for the project.

```bash
php tests/run.php
```

--------------------------------

### Development commands

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/nuget/README.md

Commands to run tests and pack the NuGet package for development.

```bash
dotnet test tests
dotnet pack -c Release
```

--------------------------------

### Run tests per package

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/README.md

Commands to run tests for each package in the repository. Each command targets a specific package directory as noted in the comments.

```bash
dart test                                   # pub_dev/
ruby test/chicago_charter_bus_rental_test.rb # rubygems/
php tests/run.php                           # packagist/
dotnet test tests                           # nuget/
python3 -m unittest -q                      # smithery-ai/chicago-group-travel/scripts/
```

--------------------------------

### CharterPlanner.RecommendFleet

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/nuget/README.md

Returns the fewest vehicles that seat everyone and, among those, the fewest spare seats. Optionally include the party bus and trolley by passing Vehicle.All.

```APIDOC
## CharterPlanner.RecommendFleet

### Description
Returns the fewest vehicles that seat everyone and, among those, the fewest spare seats. Optionally include the party bus and trolley by passing Vehicle.All.

### Method
Method call

### Endpoint
CharterPlanner.RecommendFleet(passengers, vehicles = null)

### Parameters
#### Parameters
- **passengers** (int) - Required - The number of passengers to seat.
- **vehicles** (Vehicle[]) - Optional - The set of vehicle classes to consider. Defaults to the standard fleet; pass Vehicle.All to include party bus and trolley.

### Request Example
```csharp
var plan = CharterPlanner.RecommendFleet(headcount);
```

### Response
#### Success Response
- **plan** (object) - The recommended fleet plan.
- **plan.Summary** (string) - A human-readable summary of the fleet composition and spare seats.

#### Response Example
```csharp
// 1 x SuperCoach (50-57 seats) + 1 x Small Coach Bus (22-28 seats)
// = 85 seats for 84 passengers, 1 spare
```
```

--------------------------------

### CharterPlanner.HeadcountWithBuffer

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/nuget/README.md

Adds a rounded-up safety margin to the confirmed headcount, defaulting to 5% for late additions.

```APIDOC
## CharterPlanner.HeadcountWithBuffer

### Description
Adds a rounded-up safety margin to the confirmed headcount, defaulting to 5% for late additions.

### Method
Method call

### Endpoint
CharterPlanner.HeadcountWithBuffer(confirmed, percent = 5)

### Parameters
#### Parameters
- **confirmed** (int) - Required - The confirmed headcount.
- **percent** (int) - Optional - The percentage buffer to add. Defaults to 5.

### Request Example
```csharp
var headcount = CharterPlanner.HeadcountWithBuffer(80);
```

### Response
#### Success Response
- **headcount** (int) - The buffered headcount.

#### Response Example
```csharp
// 84
```

### Error Handling
- Throws ArgumentOutOfRangeException if the headcount is below 1.
```

--------------------------------

### Run fleet plan unit tests

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/smithery-ai/README.md

Command to run the unit tests for the fleet_plan.py script. Execute from the scripts directory using Python's unittest module.

```bash
cd chicago-group-travel/scripts && python3 -m unittest -q

```

--------------------------------

### Resources::recommendFleet(int $passengers, ?array $vehicles = null)

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/packagist/README.md

Returns the fewest vehicles that seat everyone and, among those, the fewest spare seats. Optionally pass Vehicle::all() to include the party bus and trolley.

```APIDOC
## Resources::recommendFleet(int $passengers, ?array $vehicles = null)

### Description
Returns the fewest vehicles that seat everyone and, among those, the fewest spare seats. Optionally pass Vehicle::all() to include the party bus and trolley.

### Method
PHP static method

### Parameters
- **$passengers** (int) - Required - Number of passengers to seat.
- **$vehicles** (?array) - Optional - List of vehicle classes to consider; defaults to standard fleet, pass Vehicle::all() to include party bus and trolley.

### Return Value
Returns a fleet plan object with a summary() method that outputs a human-readable plan.
```

--------------------------------

### Resources::headcountWithBuffer(int $confirmed, int $percent = 5)

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/packagist/README.md

Adds a rounded-up safety margin to a confirmed headcount, defaulting to 5% for late additions.

```APIDOC
## Resources::headcountWithBuffer(int $confirmed, int $percent = 5)

### Description
Adds a rounded-up safety margin to a confirmed headcount, defaulting to 5% for late additions.

### Method
PHP static method

### Parameters
- **$confirmed** (int) - Required - Confirmed number of passengers.
- **$percent** (int) - Optional - Percentage buffer to add; defaults to 5.

### Return Value
Returns an integer representing the headcount with the buffer applied.

### Exceptions
Throws InvalidArgumentException if the headcount is below 1.
```

--------------------------------

### CharterPlanner.VehiclesNeeded

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/nuget/README.md

Computes the simple round-up number of vehicles of a single class needed to seat the given passengers.

```APIDOC
## CharterPlanner.VehiclesNeeded

### Description
Computes the simple round-up number of vehicles of a single class needed to seat the given passengers.

### Method
Method call

### Endpoint
CharterPlanner.VehiclesNeeded(passengers, vehicle)

### Parameters
#### Parameters
- **passengers** (int) - Required - The number of passengers to seat.
- **vehicle** (Vehicle) - Required - The vehicle class to use.

### Request Example
```csharp
var count = CharterPlanner.VehiclesNeeded(headcount, Vehicle.SuperCoach);
```

### Response
#### Success Response
- **count** (int) - The number of vehicles needed.

#### Response Example
```csharp
// 2
```
```

--------------------------------

### Development commands for chicago_charter_bus_rental

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/rubygems/README.md

Commands to run the test suite and build the gem from the gemspec.

```shell
ruby test/chicago_charter_bus_rental_test.rb
gem build chicago_charter_bus_rental.gemspec
```

--------------------------------

### Require chicago-charter-bus-rental package

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/npm/README.md

Import the package to access its exported TITLE and homepage properties. The homepage field on npm should remain https://chicagosupercoachbus.com/.

```javascript
const { TITLE, homepage } = require("chicago-charter-bus-rental");
```

--------------------------------

### recommend_fleet

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/rubygems/README.md

Returns the fewest vehicles that seat everyone and, among those, the fewest spare seats. Pass vehicles: ChicagoCharterBusRental::ALL to include the party bus and trolley.

```APIDOC
## recommend_fleet

### Description
Returns the fewest vehicles that seat everyone and, among those, the fewest spare seats. Pass `vehicles: ChicagoCharterBusRental::ALL` to include the party bus and trolley.

### Method
Function call

### Parameters
- `passengers` (Integer) - Required - Number of passengers to seat.
- `vehicles` (Array) - Optional - List of vehicle classes to consider. Default is `STANDARD`. Use `ChicagoCharterBusRental::ALL` to include party bus and trolley.

### Return Value
A plan object with a `summary` method that returns a human-readable string.

### Example
```ruby
plan = ChicagoCharterBusRental.recommend_fleet(headcount)
puts plan.summary
# 1 x SuperCoach (50-57 seats) + 1 x Small Coach Bus (22-28 seats)
# = 85 seats for 84 passengers, 1 spare
```
```

--------------------------------

### Project layout for chicago-group-travel skill

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/smithery-ai/README.md

Directory structure of the skill, with SKILL.md and scripts/fleet_plan.py plus test_fleet_plan.py. The folder name matches the skill name and SKILL.md contains YAML frontmatter.

```text
smithery-ai/
└── chicago-group-travel/
    ├── SKILL.md
    └── scripts/
        ├── fleet_plan.py        # headcount -> fewest vehicles (stdlib only)
        └── test_fleet_plan.py

```

--------------------------------

### Publish skill to Smithery via CLI

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/smithery-ai/README.md

Publishes the skill to Smithery using the Smithery CLI. Requires SMITHERY_API_KEY to be set. The command specifies the skill path, namespace nbkdevs, and name chicago-group-travel.

```bash
npx @smithery/cli skill publish publish/chicago-charter-bus-rental/smithery-ai/chicago-group-travel \
  --namespace nbkdevs --name chicago-group-travel

```

--------------------------------

### headcount_with_buffer

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/rubygems/README.md

Adds a rounded-up safety margin to a confirmed headcount. Raises ArgumentError if the confirmed count is below 1.

```APIDOC
## headcount_with_buffer

### Description
Adds a rounded-up safety margin to a confirmed headcount. Raises `ArgumentError` if the confirmed count is below 1.

### Method
Function call

### Parameters
- `confirmed` (Integer) - Required - Confirmed headcount.
- `percent` (Integer) - Optional - Buffer percentage. Default is 5.

### Return Value
Integer - Headcount with buffer added.

### Example
```ruby
headcount = ChicagoCharterBusRental.headcount_with_buffer(80) # 84, +5% for late additions
```
```

--------------------------------

### Import chicago_charter_bus_rental crate

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/crates/README.md

Use this import to access the crate's homepage and TITLE items. The crate points to Chicago Charter Bus Rental.

```rust
use chicago_charter_bus_rental::{homepage, TITLE};
```

--------------------------------

### vehicles_needed

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/rubygems/README.md

Returns the simple round-up number of vehicles of a given class needed for a passenger count.

```APIDOC
## vehicles_needed

### Description
Returns the simple round-up number of vehicles of a given class needed for a passenger count.

### Method
Function call

### Parameters
- `passengers` (Integer) - Required - Number of passengers.
- `vehicle` (Constant) - Required - Vehicle class constant (e.g., `ChicagoCharterBusRental::SUPER_COACH`).

### Return Value
Integer - Number of vehicles needed.

### Example
```ruby
ChicagoCharterBusRental.vehicles_needed(headcount, ChicagoCharterBusRental::SUPER_COACH) # 2
```
```

--------------------------------

### Resources::vehiclesNeeded(int $passengers, Vehicle $vehicle)

Source: https://github.com/nbkdevs/chicago-super/blob/main/publish/chicago-charter-bus-rental/packagist/README.md

Simple round-up calculation for a single vehicle class, returning the number of vehicles needed to seat the given passengers.

```APIDOC
## Resources::vehiclesNeeded(int $passengers, Vehicle $vehicle)

### Description
Simple round-up calculation for a single vehicle class, returning the number of vehicles needed to seat the given passengers.

### Method
PHP static method

### Parameters
- **$passengers** (int) - Required - Number of passengers to seat.
- **$vehicle** (Vehicle) - Required - The vehicle class to use for the calculation.

### Return Value
Returns an integer representing the number of vehicles needed.
```