# PBS Planner — User Guide

This guide covers both planners. Reserve is a calendar-based day-off planner.
Regular suggests complete schedules using Committee-published
pairings when they are available and falls back to a manual printout import.

Start from the home page (`/`) to pick a planner, or open the planner you
need directly: `/reserve.html` for Reserve, `/regular.html` for Regular.

## What this tool is

A local planning aid for Republic Airways pilots bidding in CrewPBS. Describe
your goals — days off, a credit range, or the kind of schedule you prefer — and
the tool:

- builds candidate Reserve or Regular schedules from the published data,
- checks them against the modeled Contract, rest, and rolling-window rules,
- explains the tradeoffs and the rules it could not fully check,
- writes the CrewPBS requests that match your intent and selected schedule.

It does **not** award anything, predict an award, or talk to the company. The
Bid/Award System decides; this only helps you build a bid that says what you
mean.

When a planner says a line is **locally feasible** or shows **no conflicts found
in modeled checks**, it means only the rules it actually checked passed. The
Reserve and specialist Regular views name rules that **failed** ("Failed:") and
data-quality warnings separately ("Advisory:"); the schedule workspace lists
conflicts and counts estimated or not-modeled checks separately. None of those
gaps are treated as satisfied. The Regular planner also enforces the rolling contract
windows across your selected pairings (100 block hours per 672, 60/190 FDP
hours per 168/672, and 30 free hours per 168); these are local estimates from
the printed pairing data (block/FDP attributed to the window containing each
duty's report time), the compiled plan marks them as local-only, and if your
selection breaks one, the status names the rule and the feasibility search
looks for combinations that keep it. If a must-have goal has no verified
CrewPBS mapping, copying the bid is blocked until you review it.

## What it is not

- Not an official Republic Airways or Teamsters Local 357 product.
- Not a replacement for the Contract or the CrewPBS Pilot Handbook.
- Not connected to CrewPBS, FLiCA, or the company network in any way.
- Not a guarantee. Coverage, seniority, and the optimizer always decide.
- Under active development, so it may contain errors. Always verify the bid
  against the Contract and CrewPBS before submitting.

Bug reports and feedback: angelantoniorodz@gmail.com.

## Two planners, two calendars

**Reserve** and **Regular** bids are planned separately, because CrewPBS treats
them separately. Each has its own calendar, its own month, and its own list of
results. You can switch between them without losing your work.

## Basic use (Reserve)

1. Pick the bid month.
2. Click the days you want off. Click again to remove.
3. Use the buttons to invert your picks or just the weekends if you want to
   start from the opposite.
4. Read the correction panel:
   - "You have X days off" messages tell you how many to add or remove.
   - Sequence warnings tell you where a run is too short or too long.
5. When the calendar is valid, review the compiled bid package — it is grouped
   into required requests, strong preferences, preferred conditions, fallback
   conditions, and shared Planning Session options. Copy preserves the original
   priority order; the grouping is a review view only.
6. Copy the generated bid preferences into CrewPBS, in the order shown. Default
   Copy excludes session-only lines; when they exist, a separate
   "Copy + session lines" button includes them and the app reminds you to verify
   each in CrewPBS. A must-have goal without a verified mapping blocks both copy
   actions.

## Planning a Regular line

New users start in **Schedules**. If you previously used Basic or Advanced,
select **Schedules** in the workspace bar. Your remembered mode remains available.

1. Confirm the loaded month and base. Published pairings load automatically.
   When unavailable, open **Manual printout import** to read a printout on your
   device.
2. Set your minimum and planning-maximum credit. Under **Dates I need off**, add
   a single date or a range. Choose what you prefer: a balanced schedule, more
   weekends free, more days off, higher credit per workday, or commute-friendly
   trips. These preferences rank whole schedules; they do not exclude trips.
3. Open **Commute and required settings** if needed. Enter report-after and
   release-before times; these are strict boundaries. Requiring that window or
   every weekend off makes it a condition for candidate schedules. Optional
   off-block waivers are applied only when you explicitly enable them.
4. Select **Find schedules**. Up to three complete combinations appear with
   credit, days off, weekends and trip dates. The search is bounded; it may not
   find every possible combination or the global optimum. If the first pass is
   budget-limited, the planner automatically tries a wider search. If it still
   finds nothing, it says whether the pool had no usable trips, could not reach
   your credit minimum, exhausted the search budget, or found no complete
   schedule. A zero result is never proof that your goals are impossible.
5. Choose **Use this schedule**. The calendar now shows only that schedule's
   trips. Goals collapse to a summary; open **Your goals** to edit them.
6. Click a calendar trip to **Replace** it. Fitting replacements are shown first,
   including pairings borrowed from other suggestions. The preview checks the
   whole receiving schedule and lists changes to credit, days off and weekends,
   plus every trip it would remove. Selecting **Also show drafts needing repair**
   allows experiments with conflicts. Those drafts cannot be prepared/exported
   until the listed conflicts are resolved.
7. Under **Trips, locks and details**, inspect a trip, remove it, or lock it for
   future searches. Locked trips cannot be removed by a swap. **Undo schedule
   edit** restores the previous selection and checks it against your current
   goals.
8. Changing goals keeps your current schedule. It is rechecked immediately and
   new suggestions appear alongside it. Choose an update only when you want it.
9. Select **Prepare CrewPBS bid**. Review the actual copy order and limitations.
   **Copy goal requests** and **Download goal requests** exclude session-dependent
   dated pairing and off-block option lines. **Copy with dated pairings / session
   lines** includes them for verification in the open CrewPBS session.

Schedules are local examples, not awards or all-or-nothing CrewPBS requests.
**No conflicts found in modeled schedule checks** describes only the checks run.
Missing duty data, prior/next-month history, time-zone/day-boundary limitations
and unverified regulatory coverage remain visible in **Check details and
limitations**. The planner does not claim full FAR compliance.

**Forecast, seniority and data sources** contains published staffing context and
source details. Forecasts are separate from your personal schedule preferences;
the new candidate ranking does not claim personalized award odds.

## Regular specialist tools: Basic and Advanced

Open **More planning tools** for **Preference filters (Basic)** or **Manual trip
ranking (Advanced)**. These retain their existing controls and independent
working selections within the Regular plan. Switching to Schedules for the first
time can start a draft from an existing manual selection, which is revalidated
as one schedule rather than interpreted as ranked overlapping alternatives.

1. Select **Basic** or **Advanced** under More planning tools. Basic turns filters into
   CrewPBS bid preferences; Advanced lets you inspect, select, and rank trips.
   The choice is remembered, and filters/goals are shared between modes.
2. Optional: start from a **profile** — I commute, I live in base, Dates off,
   Weekends off, Higher credit per day, Fewer deadheads, Longer trips, or More
   days off. A profile only sets the controls and lists every change it made;
   **Start from blank** resets them. "Dates off" just takes you to Protected
   off days — it never guesses your dates.
3. Open the Regular planner. The Committee-published pairing list for the bid
   month loads automatically; the import section is only a fallback for months
   they have not published yet.
4. Confirm the base in the filter bar; the planner defaults to the base with
   the most trips.
5. Filter by credit/day, weekend-free, deadheads, airport, report/release times,
   or pairing ID; set the credit target. In Advanced, sort by desirability,
   start date, credit, or length.
6. In Advanced, hover, focus, or tap a row to see the trip and its score
   breakdown. On phones and tablets the details open as a bottom sheet; use
   Select to add a trip without opening details.
7. Add protected off days — a single date or a range (leave End empty for one
   day). In Advanced they are blocked on the calendar with an OFF marker. The
   minimum and planning-maximum credit values are controlling: Basic generates
   no preferences and Advanced blocks the skeleton when the schedule falls
   outside that window.

   **Goal importance** sets how strongly each goal is requested: Default keeps
   the generator's class, or choose Must have, Strong, Preferred, or Backup.
   Demoting a must-have goal can unblock copying; the plan then will not
   request it as required. Every generated line also has a class selector in
   the review, so you can re-rank requests after seeing them. Classes are
   visible as Must-have requests, Strong preferences, Preferred conditions, and
   Backup requests. Each request also names the goal it came from (for example
   "Goal: Minimum credit · Prefer") and whether it still needs verification in
   CrewPBS.
8. In **Basic**, choose General bid preferences or Trip bid preferences.
   Filters apply live. General maps filters plus the weight sliders to CrewPBS
   conditions. Trip groups all eligible pairings with their dates and also
   compiles the shared goals — protected off days, the credit window,
   consecutive-working-day protection, and per-date avoids — ahead of the
   pairing lines, which are fallback/session-gated. Both styles show the same
   compiled package and limitations. Eligible
   trips also appear on the Basic calendar (protected days show OFF, weekends
   shade when the filter is active). Click a pairing group or calendar chip for
   details. Use Exclude to remove a pairing from the eligible pool and
   Restore to bring it back. If no locally feasible line fits, no preferences are generated
   and one-click relaxations are offered. Reset clears filters, protected days,
   and exclusions.

   Controls start at 0 (no filter). Raising one narrows the eligible trips and
   generates the matching General preference: Commutable adds Work Period
   Report/Release Time, Credit per day adds Pairing Credit Per Day, Weekends
   Off limits weekend days per trip and adds As Many Weekends Off, and
   Multi-day keeps trips longer than the chosen number of days and adds
   Pairing Length in Days. The Multi-day slider is a literal day count, not a
   weight. The status shows how many trips each control removed; a Clear
   weight filters relaxation appears if the pool becomes empty. The separate
   “Only multi-day trips” checkbox remains a hard filter.
   In **Advanced**, select trips to build a demo bid and read the
   corrections/notices and advice. Overlapping trips are treated as **ranked
   alternatives**: only one will be awarded. Use the ↑/↓ buttons to set
   priority. An alternative is rejected if choosing it would break the
   Contract or rest rules.
9. In Advanced, the calendar shows protected days (OFF), and when
   "Weekend-free only" is checked, weekends are shaded as excluded. Selected
   trips are green (primary/no conflict), amber (ranked alternative), or red
   (conflict).
   Drag an event onto another overlapping trip or onto its day cell to reorder
   the alternatives;
   click a red event to remove it, or a green/amber event for details. On
   touch devices, use the ↑/↓ buttons in Selected trips to rank.
10. Copy or download the generated bid preferences (Basic) or the bid skeleton
    (Advanced). Download saves a plain text file ready to paste into CrewPBS.
11. Tune the desirability algorithm — a few weight sliders in Basic, the full
    editor in Advanced. Changes are saved in your browser; export/import the JSON to share.

The algorithm scores are planning heuristics, not award predictions.
Competition labels come from a separate "popular assumptions" model in the
ruleset — what trips most crew members tend to want — so they do not shift
when you change your own preference sliders. Seniority-informed line and
reserve bands are available in the [Bid package stats](#bid-package-stats-forecast)
panel described below; they remain estimates, not award predictions.

## Saving and sharing

- Your work stays in your browser's local storage on your device.
- Both planners support share links. A Regular share carries the plan state —
  bid month, workspace mode, profile, goals and importance, filters, protected
  days, schedule candidates, the active schedule, trip locks and recent undo,
  exclusions, selected trips and ranking, request classes, and dataset identity
  — and the recipient's planner rechecks the schedules and regenerates the bid
  text. Generated preferences stay available through Copy and Download on each
  side.
- The Regular planner autosaves the current plan in your browser. Reopening it
  restores the plan only when the pairing dataset matches. A plan saved for
  another bid month, dataset, or pinned publication time is refused with a warning; a
   manual-import plan is restored with a dataset-provenance warning.
- Schedule-first plans also save the active dated pairings, suggested candidates,
  required settings, locks and recent undo history. Share links carry these
  inputs. Rule results and bid text are recalculated on restore; a missing
  pairing is reported as an unresolved draft rather than silently removed.
- **Data and versions** lists where the pairings, forecast, and seniority
  lists came from (CMS, static file, or manual import), which month they cover,
  and the contract-rules, CrewPBS option-list, and planner versions used.
- In Advanced, **Other pairings in this date range** explains what changes if
  you swap a ranked alternative for the current choice (credit, working days,
  weekend effect, and assumed competition). No data is sent anywhere.

## Printing

A print view produces a clean copy of the correction list and bid
preferences, suitable for your bid notes.

## Privacy

- No accounts. No uploads from crew members. No analytics.
- Published datasets (seniority, forecast, pairings) are downloaded from the
  site or the Committee CMS; your plans and settings stay in your browser.
- If you use the fallback pairing import, the PDF is read in your browser and
  the parsed result is never stored or sent anywhere.

## Seniority (optional)

If the union publishes a de-identified seniority list (`data/seniority.json`
next to the planner page), the Regular planner loads it automatically — you
never upload anything. Enter your employee number under
**Seniority (optional)**:

- The published list contains only hashed crew ids, seniority ranks, and the
  current position (base/equipment/seat) — no names.
- Your employee number is hashed on your device and only the hash is kept;
  the number itself is never stored.
- The planner shows your **Base Sen** with your base (rank within your
  base/equipment/seat group, e.g. "Base Sen 5 (BOS)") and your **Seniority**
  (company-wide rank). Your base is also selected in the Base filter when the
  bid package includes it.
- "Clear" removes the stored hash.
- Seniority-informed predictions use this position and are labeled as
  estimates, never guarantees.

## Bid package stats (forecast)

Both planners can show a **Bid package stats** panel with the month's
Reserve Allocation by Base (call-period split per base) and Anticipated Bid
Lines (hard lines and reserve/partial counts), plus — when your seniority is applied on
the Regular side — your estimated standing against the published counts:

- The matrices are **company-published forecasts**, not contract values; they
  change every month and the panel always labels its source.
- The planner uses the published matrices when the Committee posts them
  (through the committee CMS or as `data/forecast.json` next to the page), and
  falls back to the shipped defaults (December 2026) for other months.
- Your standing is an estimate from your bidding-pool rank and the published
  line counts. Crew marked "No Bid" in the seniority list do not compete.
- The Committee maintains the matrices on the forecast admin page
  (paste or PDF import, editable tables, then publish to the CMS or export
  `data/forecast.json`).
- It is a planning aid, **not** the award. Verify against the actual bid
  package.

## Common questions

**Why exactly 12 days off?** The Contract sets a minimum of 12 days off per
bid period. Reserve lines are built to a fixed 75:00 guarantee, which works out
to 12 days off in practice. The tool checks your target of 12 and explains
every mismatch.

**Why does it complain about a single day off?** The Contract requires off
blocks of at least two days, except at the first or last day of the bid
month, unless you request a single day off. The tool reproduces that rule.

**Why does the Regular side never generate "Work on" lines for Reserve?**
CrewPBS offers only `Consecutive Working Days` on the Reserve tab. `Work on
Date`, work-period options, and all pairing/layover options exist on the
Regular tab only, so generating them for Reserve would be ignored.

**Something looks wrong.** Compare against the Contract and the Handbook, then
bring it to the Scheduling Committee. Every rule in the tool cites its source
in `docs/rules/`.
