elliot-stack 1.0.36 → 1.0.38

package/skills/estack-flight-planner/references/config_schema.md

@@ -1,156 +1,156 @@
-# Config Schema — `~/.flight-planner/config.json`
-
-The skill stores user preferences in this file. It's outside `~/.claude/skills/` so the e-stack installer never overwrites it.
-
-## Full schema
-
-```json
-{
-  "serpapi_key": "abc123 or null",
-
-  "budget_usd": 200,
-  "budget_strength": "soft",
-
-  "airline_preferences": ["UA", "DL"],
-  "airline_preference_strength": "soft",
-
-  "nonstop_preference": "preferred",
-  "nonstop_strength": "soft",
-
-  "time_priority_bands": ["11:00-14:00", "14:00-22:00"],
-  "time_priority_strength": "soft",
-
-  "home_airport": null,
-  "frequent_destinations": [],
-
-  "shuttle_service": null
-}
-```
-
-## Field reference
-
-### `serpapi_key`
-- Type: string or null
-- Your SerpAPI key for Google Flights queries. If null, the skill falls back to WebSearch (less comprehensive — see SKILL.md).
-- Get one at https://serpapi.com/manage-api-key.
-
-### `budget_usd`
-- Type: int
-- Max flight price in USD.
-
-### `budget_strength`
-- Type: `"hard"` or `"soft"`
-- `hard` = filter out flights above budget. `soft` = include them but rank cheaper ones higher.
-
-### `airline_preferences`
-- Type: array of IATA airline codes (e.g., `["UA", "DL"]`)
-- Empty array = any airline.
-
-### `airline_preference_strength`
-- Type: `"hard"` or `"soft"`
-- `hard` = only show flights on these airlines. `soft` = prefer them but show others too.
-
-### `nonstop_preference`
-- Type: `"required"`, `"preferred"`, or `"no_preference"`
-
-### `nonstop_strength`
-- Type: `"hard"` or `"soft"`
-- Combined with `nonstop_preference`:
-  - `required` + `hard` = filter out anything with stops
-  - `required` + `soft` = treat stopovers as a downside but still show them
-  - `preferred` + `soft` = rank nonstops first, show stops second (typical setup)
-  - `no_preference` = strength is ignored
-
-### `time_priority_bands`
-- Type: array of `"HH:MM-HH:MM"` ranges in 24-hour time
-- Departures inside the first band rank highest; second band second; outside all bands rank lowest.
-
-### `time_priority_strength`
-- Type: `"hard"` or `"soft"`
-- `hard` = filter out flights outside all bands. `soft` = include but rank lower.
-
-### `home_airport`
-- Type: IATA code or null
-- Optional. If set, the skill suggests it when asking for origin in Phase 1 (but still asks).
-
-### `frequent_destinations`
-- Type: array of IATA codes
-- Optional. Surfaced as suggestions when asking for destination.
-
-### `shuttle_service`
-- Type: object or null
-- If non-null, the skill pairs flights with ground shuttle runs. See `references/shuttle_schedules.md` for the full sub-schema.
-
-## Example configs
-
-### Frequent flier, one home airport, picky about times
-
-```json
-{
-  "serpapi_key": "sk_xxx",
-  "budget_usd": 350,
-  "budget_strength": "soft",
-  "airline_preferences": ["DL"],
-  "airline_preference_strength": "hard",
-  "nonstop_preference": "required",
-  "nonstop_strength": "hard",
-  "time_priority_bands": ["07:00-10:00", "17:00-20:00"],
-  "time_priority_strength": "soft",
-  "home_airport": "JFK",
-  "frequent_destinations": ["LAX", "SFO", "SEA"],
-  "shuttle_service": null
-}
-```
-
-### Casual traveler, cost-sensitive, flexible
-
-```json
-{
-  "serpapi_key": null,
-  "budget_usd": 250,
-  "budget_strength": "hard",
-  "airline_preferences": [],
-  "airline_preference_strength": "soft",
-  "nonstop_preference": "preferred",
-  "nonstop_strength": "soft",
-  "time_priority_bands": [],
-  "time_priority_strength": "soft",
-  "home_airport": null,
-  "frequent_destinations": [],
-  "shuttle_service": null
-}
-```
-
-### Suburban user with a shuttle service
-
-```json
-{
-  "serpapi_key": "sk_xxx",
-  "budget_usd": 200,
-  "budget_strength": "soft",
-  "airline_preferences": ["UA"],
-  "airline_preference_strength": "soft",
-  "nonstop_preference": "preferred",
-  "nonstop_strength": "soft",
-  "time_priority_bands": ["11:00-14:00", "14:00-22:00"],
-  "time_priority_strength": "soft",
-  "home_airport": null,
-  "frequent_destinations": ["EWR", "LGA"],
-  "shuttle_service": {
-    "name": "Acme Airport Express",
-    "schedule_urls": ["https://acme.example.com/schedule"],
-    "costs": {"ORD": 60, "IND": 30},
-    "home_timezone": "America/New_York",
-    "airport_timezones": {"ORD": "America/Chicago", "IND": "America/New_York"}
-  }
-}
-```
-
-## Strength semantics recap
-
-| Strength | Behavior |
-|---|---|
-| `hard` | Filter applied strictly — non-matching flights are excluded from output |
-| `soft` | Filter applied as a rank weight — non-matching flights still shown, flagged with `soft_filter_violations` and sorted below matching ones |
-
-When hard filters return zero results, the skill runs `filter_flights.py --cluster-analysis` to see which constraint(s) eliminated which flight counts, then proposes specific relaxations.
+# Config Schema — `~/.flight-planner/config.json`
+
+The skill stores user preferences in this file. It's outside `~/.claude/skills/` so the e-stack installer never overwrites it.
+
+## Full schema
+
+```json
+{
+  "serpapi_key": "abc123 or null",
+
+  "budget_usd": 200,
+  "budget_strength": "soft",
+
+  "airline_preferences": ["UA", "DL"],
+  "airline_preference_strength": "soft",
+
+  "nonstop_preference": "preferred",
+  "nonstop_strength": "soft",
+
+  "time_priority_bands": ["11:00-14:00", "14:00-22:00"],
+  "time_priority_strength": "soft",
+
+  "home_airport": null,
+  "frequent_destinations": [],
+
+  "shuttle_service": null
+}
+```
+
+## Field reference
+
+### `serpapi_key`
+- Type: string or null
+- Your SerpAPI key for Google Flights queries. If null, the skill falls back to WebSearch (less comprehensive — see SKILL.md).
+- Get one at https://serpapi.com/manage-api-key.
+
+### `budget_usd`
+- Type: int
+- Max flight price in USD.
+
+### `budget_strength`
+- Type: `"hard"` or `"soft"`
+- `hard` = filter out flights above budget. `soft` = include them but rank cheaper ones higher.
+
+### `airline_preferences`
+- Type: array of IATA airline codes (e.g., `["UA", "DL"]`)
+- Empty array = any airline.
+
+### `airline_preference_strength`
+- Type: `"hard"` or `"soft"`
+- `hard` = only show flights on these airlines. `soft` = prefer them but show others too.
+
+### `nonstop_preference`
+- Type: `"required"`, `"preferred"`, or `"no_preference"`
+
+### `nonstop_strength`
+- Type: `"hard"` or `"soft"`
+- Combined with `nonstop_preference`:
+  - `required` + `hard` = filter out anything with stops
+  - `required` + `soft` = treat stopovers as a downside but still show them
+  - `preferred` + `soft` = rank nonstops first, show stops second (typical setup)
+  - `no_preference` = strength is ignored
+
+### `time_priority_bands`
+- Type: array of `"HH:MM-HH:MM"` ranges in 24-hour time
+- Departures inside the first band rank highest; second band second; outside all bands rank lowest.
+
+### `time_priority_strength`
+- Type: `"hard"` or `"soft"`
+- `hard` = filter out flights outside all bands. `soft` = include but rank lower.
+
+### `home_airport`
+- Type: IATA code or null
+- Optional. If set, the skill suggests it when asking for origin in Phase 1 (but still asks).
+
+### `frequent_destinations`
+- Type: array of IATA codes
+- Optional. Surfaced as suggestions when asking for destination.
+
+### `shuttle_service`
+- Type: object or null
+- If non-null, the skill pairs flights with ground shuttle runs. See `references/shuttle_schedules.md` for the full sub-schema.
+
+## Example configs
+
+### Frequent flier, one home airport, picky about times
+
+```json
+{
+  "serpapi_key": "sk_xxx",
+  "budget_usd": 350,
+  "budget_strength": "soft",
+  "airline_preferences": ["DL"],
+  "airline_preference_strength": "hard",
+  "nonstop_preference": "required",
+  "nonstop_strength": "hard",
+  "time_priority_bands": ["07:00-10:00", "17:00-20:00"],
+  "time_priority_strength": "soft",
+  "home_airport": "JFK",
+  "frequent_destinations": ["LAX", "SFO", "SEA"],
+  "shuttle_service": null
+}
+```
+
+### Casual traveler, cost-sensitive, flexible
+
+```json
+{
+  "serpapi_key": null,
+  "budget_usd": 250,
+  "budget_strength": "hard",
+  "airline_preferences": [],
+  "airline_preference_strength": "soft",
+  "nonstop_preference": "preferred",
+  "nonstop_strength": "soft",
+  "time_priority_bands": [],
+  "time_priority_strength": "soft",
+  "home_airport": null,
+  "frequent_destinations": [],
+  "shuttle_service": null
+}
+```
+
+### Suburban user with a shuttle service
+
+```json
+{
+  "serpapi_key": "sk_xxx",
+  "budget_usd": 200,
+  "budget_strength": "soft",
+  "airline_preferences": ["UA"],
+  "airline_preference_strength": "soft",
+  "nonstop_preference": "preferred",
+  "nonstop_strength": "soft",
+  "time_priority_bands": ["11:00-14:00", "14:00-22:00"],
+  "time_priority_strength": "soft",
+  "home_airport": null,
+  "frequent_destinations": ["EWR", "LGA"],
+  "shuttle_service": {
+    "name": "Acme Airport Express",
+    "schedule_urls": ["https://acme.example.com/schedule"],
+    "costs": {"ORD": 60, "IND": 30},
+    "home_timezone": "America/New_York",
+    "airport_timezones": {"ORD": "America/Chicago", "IND": "America/New_York"}
+  }
+}
+```
+
+## Strength semantics recap
+
+| Strength | Behavior |
+|---|---|
+| `hard` | Filter applied strictly — non-matching flights are excluded from output |
+| `soft` | Filter applied as a rank weight — non-matching flights still shown, flagged with `soft_filter_violations` and sorted below matching ones |
+
+When hard filters return zero results, the skill runs `filter_flights.py --cluster-analysis` to see which constraint(s) eliminated which flight counts, then proposes specific relaxations.

package/skills/estack-flight-planner/references/flight_history_schema.md

@@ -1,97 +1,97 @@
-# Flight History Schema — `~/.flight-planner/flight_history.json`
-
-Append-only log of every flight search. Used as passive context so the skill can recognize patterns over time ("you've been booking the ~$180 range lately").
-
-## File format
-
-A single JSON array of entry objects. The file is created the first time the skill writes to it; until then the file does not exist.
-
-```json
-[
-  { entry 1 },
-  { entry 2 },
-  ...
-]
-```
-
-To append safely: read the array, push the new entry, write the file back. If the file is missing or corrupt, start a fresh array.
-
-## Entry types
-
-There are two entry types. Each search produces one of each (under normal flow).
-
-### `search_started`
-
-Written immediately after the user confirms Phase 2 preferences and before `fetch_flights.py` runs. Captures what they were looking for, even if they abandon the search before booking.
-
-```json
-{
-  "type": "search_started",
-  "id": "2026-05-11T14:23:07-04:00-3f9a",
-  "timestamp": "2026-05-11T14:23:07-04:00",
-  "dates": ["2026-05-15", "2026-05-16"],
-  "origins": ["IND", "ORD"],
-  "destinations": ["EWR", "LGA"],
-  "config_snapshot": {
-    "budget_usd": 200,
-    "budget_strength": "soft",
-    "airline_preferences": ["UA", "DL"],
-    "airline_preference_strength": "soft",
-    "nonstop_preference": "preferred",
-    "nonstop_strength": "soft",
-    "time_priority_bands": ["11:00-14:00", "14:00-22:00"],
-    "time_priority_strength": "soft",
-    "had_shuttle": false
-  }
-}
-```
-
-**Fields:**
-- `id` — unique identifier for this search. Format: ISO timestamp + 4-char random hex.
-- `timestamp` — ISO 8601 with timezone offset
-- `dates` — list of YYYY-MM-DD strings the user searched
-- `origins`, `destinations` — list of IATA codes used for this search (Phase 1 input)
-- `config_snapshot` — preferences as-applied to this search (after any Phase 2 overrides). Don't include `serpapi_key`.
-
-### `selection_made`
-
-Written after the user picks a flight from the ranked output. Links back to the `search_started` entry.
-
-```json
-{
-  "type": "selection_made",
-  "timestamp": "2026-05-11T14:31:42-04:00",
-  "search_started_id": "2026-05-11T14:23:07-04:00-3f9a",
-  "chosen_flight": {
-    "date": "2026-05-15",
-    "flight": "UA 1234",
-    "from": "IND",
-    "to": "EWR",
-    "departs": "13:45",
-    "arrives": "16:20",
-    "price": 178,
-    "stops": 0,
-    "airline": "United"
-  },
-  "chosen_shuttle": null,
-  "total_cost": 178,
-  "options_shown_count": 7
-}
-```
-
-**Fields:**
-- `search_started_id` — id of the matching `search_started` entry
-- `chosen_flight` — the flight dict from `filter_flights.py` output
-- `chosen_shuttle` — the shuttle dict from `pair_shuttles.py` if pairing was used, else null
-- `total_cost` — flight + shuttle USD
-- `options_shown_count` — how many options the user could pick from
-
-## How the skill uses the log
-
-- **Pattern surfacing (passive):** When relevant, the skill can read recent entries to note things like "Your last 3 trips picked flights between $160–$200 — flagging the $245 option as out-of-pattern."
-- **Abandoned-search detection:** A `search_started` with no matching `selection_made` within the same day suggests an abandoned search. The skill should not bring these up unprompted.
-- **Privacy:** The log lives on the user's local disk, unencrypted. Don't put the SerpAPI key or any other secret in `config_snapshot`.
-
-## Pruning
-
-The file grows by 2 entries per booking. Pruning is the user's responsibility — they can delete it or keep it indefinitely. The skill does not prune.
+# Flight History Schema — `~/.flight-planner/flight_history.json`
+
+Append-only log of every flight search. Used as passive context so the skill can recognize patterns over time ("you've been booking the ~$180 range lately").
+
+## File format
+
+A single JSON array of entry objects. The file is created the first time the skill writes to it; until then the file does not exist.
+
+```json
+[
+  { entry 1 },
+  { entry 2 },
+  ...
+]
+```
+
+To append safely: read the array, push the new entry, write the file back. If the file is missing or corrupt, start a fresh array.
+
+## Entry types
+
+There are two entry types. Each search produces one of each (under normal flow).
+
+### `search_started`
+
+Written immediately after the user confirms Phase 2 preferences and before `fetch_flights.py` runs. Captures what they were looking for, even if they abandon the search before booking.
+
+```json
+{
+  "type": "search_started",
+  "id": "2026-05-11T14:23:07-04:00-3f9a",
+  "timestamp": "2026-05-11T14:23:07-04:00",
+  "dates": ["2026-05-15", "2026-05-16"],
+  "origins": ["IND", "ORD"],
+  "destinations": ["EWR", "LGA"],
+  "config_snapshot": {
+    "budget_usd": 200,
+    "budget_strength": "soft",
+    "airline_preferences": ["UA", "DL"],
+    "airline_preference_strength": "soft",
+    "nonstop_preference": "preferred",
+    "nonstop_strength": "soft",
+    "time_priority_bands": ["11:00-14:00", "14:00-22:00"],
+    "time_priority_strength": "soft",
+    "had_shuttle": false
+  }
+}
+```
+
+**Fields:**
+- `id` — unique identifier for this search. Format: ISO timestamp + 4-char random hex.
+- `timestamp` — ISO 8601 with timezone offset
+- `dates` — list of YYYY-MM-DD strings the user searched
+- `origins`, `destinations` — list of IATA codes used for this search (Phase 1 input)
+- `config_snapshot` — preferences as-applied to this search (after any Phase 2 overrides). Don't include `serpapi_key`.
+
+### `selection_made`
+
+Written after the user picks a flight from the ranked output. Links back to the `search_started` entry.
+
+```json
+{
+  "type": "selection_made",
+  "timestamp": "2026-05-11T14:31:42-04:00",
+  "search_started_id": "2026-05-11T14:23:07-04:00-3f9a",
+  "chosen_flight": {
+    "date": "2026-05-15",
+    "flight": "UA 1234",
+    "from": "IND",
+    "to": "EWR",
+    "departs": "13:45",
+    "arrives": "16:20",
+    "price": 178,
+    "stops": 0,
+    "airline": "United"
+  },
+  "chosen_shuttle": null,
+  "total_cost": 178,
+  "options_shown_count": 7
+}
+```
+
+**Fields:**
+- `search_started_id` — id of the matching `search_started` entry
+- `chosen_flight` — the flight dict from `filter_flights.py` output
+- `chosen_shuttle` — the shuttle dict from `pair_shuttles.py` if pairing was used, else null
+- `total_cost` — flight + shuttle USD
+- `options_shown_count` — how many options the user could pick from
+
+## How the skill uses the log
+
+- **Pattern surfacing (passive):** When relevant, the skill can read recent entries to note things like "Your last 3 trips picked flights between $160–$200 — flagging the $245 option as out-of-pattern."
+- **Abandoned-search detection:** A `search_started` with no matching `selection_made` within the same day suggests an abandoned search. The skill should not bring these up unprompted.
+- **Privacy:** The log lives on the user's local disk, unencrypted. Don't put the SerpAPI key or any other secret in `config_snapshot`.
+
+## Pruning
+
+The file grows by 2 entries per booking. Pruning is the user's responsibility — they can delete it or keep it indefinitely. The skill does not prune.