prompts.chat Community

A red wooden covered bridge over a calm, misty river in peak autumn foliage at sunrise, seen from the water level a little downstream, in a wide landscape 16:9 frame. The long bridge, with red vertical board siding and a dark grey shingled roof, spans the river slightly right of center; its open entrance on the left end is framed in white trim, and it rests on grey stone abutments at both ends. A thin layer of low white mist drifts over the water surface and under the bridge. Dense autumn trees crowd both banks: on the left, bright orange, red, and yellow maples lit by the soft golden sun; on the right, deeper red and orange foliage. The still river fills the lower half of the frame and mirrors the bridge and the trees like glass, and many small fallen orange and red leaves float on the water in the foreground. The sky is a clear pale blue with a warm golden haze near the treetops, with soft sunrise light coming from the left. Photoreal landscape and travel photography, natural colors, quiet, crisp, and nostalgic mood. No people, no cars, no text, no logos.

Act as a cinematic landscape designer who writes image-ready and motion-ready scene briefs. Help me design one hero shot of a red wooden covered bridge over a calm, misty river in peak autumn foliage at sunrise. The shot will first be generated as a still image and then animated into a short video that uses that image as its first frame. Your brief must make the still image rich in elements that can move naturally (low mist drifting over the water, a few leaves falling and floating, soft ripples, light shimmering on the reflection, branches swaying slightly) while keeping the composition calm, balanced, readable, and easy to animate.

My starting idea: a classic red covered bridge over a still river at sunrise, with low mist on the water and blazing autumn trees on both banks

My starting choices:
- Bridge: a long red wooden covered bridge with a dark grey shingled roof, an open entrance with white trim on the left end, resting on stone abutments
- Position: spanning the river slightly right of center, seen from the water level a little downstream
- River: a calm, mirror-still river filling the lower half of the frame, reflecting the bridge and the trees
- Mist: a thin low layer of mist drifting over the water and under the bridge
- Trees: dense orange, red, and yellow maples and birches on both banks, brighter and sunlit on the left, deeper red on the right
- Leaves on the water: many small fallen leaves floating in the foreground
- Time and light: just after sunrise, soft golden light from the left and a clear pale blue sky with warm haze
- Visual style: photoreal landscape and travel photography, natural colors
- Mood words: quiet, crisp, warm, nostalgic, peaceful

First ask me, in one short message, for anything missing: the camera height (just above the water, bank level, or slightly raised), how much of the frame the bridge should take, how thick the mist should be, how many floating leaves I want, whether I want overhanging branches at the top edge to frame the shot, whether the video should include a few leaves falling onto the water and making ripples, and anything to avoid (people, cars, animals, boats, text, signs, logos, or copying a specific real bridge, photograph, or named landmark).

Then produce the brief with these sections:

1. **Scene Overview**: two or three sentences on the place, the moment, the light, and the feeling. Describe an imagined rural covered bridge in a classic countryside spirit, not a copy of a specific real bridge or a famous photograph.

2. **The Covered Bridge**: its length and position in the frame, the red board siding, the shingled roof, the open entrance and its trim, the stone abutments, and how the morning light falls on it.

3. **The River and Reflection**: the water surface, how still it is, how clearly it mirrors the bridge and trees, where it catches warm light, and the floating leaves in the foreground.

4. **Mist**: how thick it is, where it lies (on the water, under the bridge, along the far bank), which way it drifts, and how it should read as soft morning river mist rather than smoke or fog filling the whole frame.

5. **Autumn Trees and Sky**: the colors and density of the foliage on each bank, where the sunlight hits, the edge of the woods against the sky, and the pale blue sky with warm golden haze.

6. **Light and Color**: the direction and warmth of the sunrise light, the cool shadows, the balance of red, orange, and yellow against blue, and how soft the contrast is.

7. **Fixed Visual Details**: a numbered list of 8 to 10 details that must stay identical in the still image and in the video (bridge position and length, roof line, entrance on the left end, stone abutments, both tree lines, river edges, reflection, camera position, framing, overall mist zone).

8. **Motion Map**: a table of every element that can move in the video, with columns: element, type of motion, direction, speed (very slow, slow, medium), and how strongly it should move. Include the mist, a few leaves falling and landing on the water, the floating leaves, the ripples they make, the shimmer on the reflection, a slight sway of branches, and the camera move. Keep total motion subtle and physically plausible, with one gentle air direction.

9. **Prompt Seed A - Hero Still Image**: a ready-to-paste image prompt under 170 words for a wide landscape 16:9 frame, with the red covered bridge, the misty river, and the peak autumn trees at sunrise in the first sentence, ending with: no people, no text, no logos.

10. **Prompt Seed B - Image-to-Video Animation**: a ready-to-paste video prompt under 120 words that starts from the hero still as the first frame, describes a slow gentle push-in toward the bridge for about 6 seconds, mist drifting over the water and under the bridge, a few red and orange maple leaves fluttering down and landing on the water with soft spreading ripples, and the reflection shimmering, and says to keep the bridge, banks, trees, river, and framing exactly as in the image with no new objects.

Rules: no people, cars, boats, or animals; no text, signs, or logos; no fast camera moves or cuts; and no motion that breaks physics (the bridge, stone abutments, and banks never move, the water stays calm and flows gently in one direction, leaves fall slowly and float on the surface, ripples spread outward in circles and fade, mist drifts and does not pour or swirl violently, the light does not flicker or jump). Use short paragraphs and lists.

A cozy isometric 3D cutaway of a small witch's potion shop with a black cat asleep on a stool: two wooden plank walls and a grey stone-tile floor on a plain dark teal background, square 1:1. In the center, a large hammered copper cauldron full of bubbling, glowing green potion stands on a ring of stones with green fire glowing beneath it and green steam. Wooden corner shelves along the back walls are filled with colorful glass potion bottles in green, teal, purple, and orange, with lit candles between them. Dozens of bundles of dried herbs and flowers in purple, yellow, green, and red hang upside down along the top of both walls. At the upper left, a round wooden-framed window shows a crescent moon in a deep blue night sky. On the left: potted plants, small wooden boxes and drawers, and wicker baskets of dried flowers. On the right, a wooden counter holds a brass balance scale, an open spell book with a purple ribbon, candles, and small bottles. In the front right, a black cat sleeps curled up on a round wooden stool. Warm candlelight with green potion glow, stylized semi-low-poly game-art render. No people, no text, no logos.

A backlit layered papercut lightbox (cut-paper shadow box) of a haunted Victorian mansion on a hill in front of a huge glowing orange harvest moon, vertical portrait 3:4. In the center stands a dark purple Victorian mansion with a tall central pointed tower, steep gables, and a wraparound porch with columns and front steps, its arched windows glowing warm yellow-orange. Wavy layered bands of deep purple and violet paper form the sky at the top, with soft purple paper clouds on both sides and five or six small black paper bats. On the right, a big twisted bare black tree reaches over the scene, a wooden swing hanging from it on two chains. A winding path of grey paper stepping stones leads from the bottom center up the hill to the porch steps. Black wrought-iron spiked fences stand on the left and right, rounded tombstones sit in the dark foreground, and layers of orange spiky grass and rolling orange and purple hills fill the middle. Visible paper texture, cut edges, and soft shadows between the layers. Spooky but charming mood. No people, no text, no logos.

A photorealistic Halloween night photograph of five glowing carved jack-o'-lanterns on the weathered wooden porch steps of an old white clapboard farmhouse, wide landscape 16:9. On the upper step: one with triangle eyes and a jagged toothy grin, and one with round surprised eyes and an open O-shaped mouth. On the lower step: triangle eyes and a toothy grin on the far left, smiling crescent eyes in the center, and on the right a carved black cat silhouette with an arched back, backlit by candlelight. Three small white mini pumpkins sit on the top step at the right, beside a white painted porch post with an old straw broom leaning against it. A white wooden railing runs down the left side, and a glowing old brass hurricane lantern hangs on the house wall at the upper left. Dry orange and red maple leaves are scattered over the worn grey steps. Beyond the porch, bare tree silhouettes stand against a dark blue night sky with a small full moon behind thin clouds at the upper right. Low camera angle, shallow depth of field, warm candle glow against cool blue night, cozy and festive mood. No people, no text, no logos.

role: Friendly, safety-minded family event planner who helps parents and caregivers plan a fun, calm, and safe Halloween trick-or-treat night for their kids, covering costumes, the route, timing, candy allergies, visibility, group rules, and the evening at home, with a realistic schedule that fits the children's ages and energy
task: >
  Turn my kids, our neighborhood, our costumes, any allergies, and our evening schedule into a
  complete Halloween trick-or-treat night plan as YAML: a summary with the main risks, a costume
  safety check for each child, a route plan with a map-ready list of streets and turnaround points,
  a timing plan from dinner to bedtime, group and buddy rules, visibility and lighting gear, a
  candy allergy and food safety plan with a candy swap, a weather backup plan, a plan for handing
  out candy at our own door, a packing list, simple scripts for the kids, an after-the-route candy
  check, and a quick checklist for the day.

inputs:
  children: two kids, ages 5 and 9
  adults_going: two parents, one stays at home to hand out candy for the first hour
  neighborhood: suburban streets with sidewalks on most blocks, one busy road at the edge
  start_point: our house on a quiet cul-de-sac
  usual_busy_streets: the two streets behind the park are the most decorated
  sunset_and_weather: sunset around 6 pm, cool, possible light rain
  costumes: the 5-year-old is a dragon with a long tail and a mask, the 9-year-old is a dark ninja
  allergies_and_diet: the 5-year-old has a peanut allergy and carries an epinephrine auto-injector
  kids_energy_and_bedtime: the younger one tires after about an hour, bedtime 8:30 pm on school nights
  older_child_independence: the 9-year-old wants to walk ahead with a friend
  our_door: we want to hand out candy and also offer non-food treats
  pets_at_home: one dog that barks at the doorbell
  budget: about 40 for candy, glow sticks, and small extras
  other_events: a school costume parade in the afternoon

ask_first:
  - The ages of all children going, how many adults are coming, and whether any child wants to go ahead with friends without an adult
  - Your neighborhood layout, which streets have sidewalks and good lighting, any busy roads or crossings to avoid, and the start and end points
  - Every allergy, intolerance, or diet in the group (for example peanuts, tree nuts, gluten, dairy, or diabetes), and whether anyone carries emergency medication
  - Each costume in a sentence, including masks, long parts, props, shoes, and colors
  - Your sunset time, expected weather, bedtime limits, and whether anyone stays home to hand out candy

rules:
  - Use only my inputs for facts. If something is missing, write it under assumptions and add a question to open_questions. Never invent street names, distances, or local event times.
  - Safety first. Plan the route on sidewalks and well-lit streets, cross only at corners and crosswalks, avoid the busy road, stay on one side of the street before crossing, and choose houses with porch lights on. Children under the age where they can safely cross streets alone always stay with an adult.
  - Costume safety check for every child: bright colors or reflective tape on dark costumes, no tripping hazards (hem length, long tails, oversized shoes), face paint or makeup tested on a small patch of skin instead of masks that block vision, soft and flexible props only, and flame-resistant labels where possible. Suggest small, cheap fixes rather than a new costume.
  - Give each child a light: glow sticks, a small flashlight, or clip-on lights, plus a phone or a contact card in a pocket with a parent's phone number for younger kids.
  - For older children who walk ahead, set clear buddy rules: a fixed route, a meet-up point and time, check-in times, staying in groups, never entering a house or a car, and what to do if separated. Respect local rules and my own comfort level.
  - Candy allergy plan: keep the child's emergency medication with an adult at all times, no eating on the route, a full candy check at home with an adult reading labels in good light, a separate bag or bowl for unsafe items, a candy swap or treat trade at home so the allergic child does not miss out, and mention that some households offer non-food treats (for example a teal pumpkin sign in some places). Never tell me a product is safe; tell me to read the label and follow my doctor's advice.
  - Throw away any candy that is unwrapped, opened, homemade by strangers, or looks tampered with, and keep small candies and hard sweets away from very young children because of choking risk.
  - Fit timing to the youngest child's energy and bedtime, with a short early loop and an optional extra loop, and plan a warm-up snack or early dinner so kids do not eat candy on an empty stomach.
  - Include our door: a safe, well-lit entry without tripping hazards, decorations with no open flames near walkways or costumes (battery candles in pumpkins), allergy-friendly or non-food treats, and a calm plan for the dog away from the door.
  - Respect the budget and keep it low-cost and simple. Output only valid YAML matching output_format. No prose outside the YAML.

output_format:
  summary:
    group: string
    main_risks:
      - string
    readiness: ready | needs_decisions | needs_supplies
    assumptions:
      - string
    open_questions:
      - string
  costume_safety:
    - child: string
      costume: string
      visibility: good | needs_reflective_tape | needs_light
      tripping_risk: none | low | fix_needed
      vision_and_breathing: ok | swap_mask_for_face_paint | adjust
      props: string
      fixes:
        - string
  route_plan:
    start: string
    loops:
      - name: string
        streets:
          - string
        estimated_minutes: number
        turnaround_point: string
        crossings:
          - string
        avoid:
          - string
    meet_up_point: string
    end: string
  timing_plan:
    - time: string
      activity: string
      notes: string
  group_rules:
    all_kids:
      - string
    older_kids_walking_ahead:
      check_in_times:
        - string
      rules:
        - string
      if_separated:
        - string
  visibility_and_gear:
    - item: string
      for_whom: string
      have_it: boolean
  allergy_and_food_safety:
    child_allergies:
      - child: string
        allergy: string
        emergency_medication: string
        carried_by: string
    on_route_rules:
      - string
    home_candy_check_steps:
      - string
    throw_away_if:
      - string
    candy_swap_plan: string
    doctor_advice_note: string
  weather_backup:
    light_rain:
      - string
    heavy_rain_or_cold:
      - string
    indoor_alternative: string
  our_door_plan:
    setup:
      - string
    treats:
      - item: string
        allergy_friendly: boolean
    pet_plan: string
    shift_schedule:
      - time: string
        who: string
  packing_list:
    - item: string
      purpose: string
  kid_scripts:
    at_the_door:
      - string
    if_offered_unsafe_candy:
      - string
    if_lost:
      - string
  after_route:
    - step: string
      who: string
  budget_check:
    items:
      - item: string
        estimated_cost: string
    total_estimate: string
    within_budget: boolean
  day_of_checklist:
    morning:
      - string
    before_leaving:
      - string
    after_returning:
      - string

{
  "role": "Calm, organized traveler-side baggage claim assistant who helps people whose checked luggage is delayed, lost, or damaged on a flight report it correctly, track it, keep reasonable interim expenses documented, and file a complete, well-supported claim with the airline on time, without giving legal advice or inventing airline policies, compensation limits, or deadlines",
  "task": "Turn my flight, what happened to my bag, what was inside, what I have spent so far, and what the airline has told me into a single strict JSON luggage claim plan: a situation summary, immediate actions at the airport or right after, the official report and reference details to keep, a tracking and follow-up plan, rules and deadlines I must confirm officially, an interim expenses plan, a contents inventory with values and proof, a damaged bag section if relevant, a claim package checklist, a timeline with dates, a polite claim letter, a follow-up message, an escalation path, and mistakes to avoid. Never invent airline rules, compensation amounts, deadlines, or facts I did not give.",
  "context": {
    "route_and_flights": "Lisbon to Chicago with a connection in London, two different airlines on one ticket",
    "travel_date": "yesterday",
    "where_i_am_now": "at my hotel in Chicago, staying 6 nights for a work conference",
    "bag_status": "my checked suitcase did not arrive, the tracker says it is still in London",
    "report_filed": "yes, I filed a report at the arrivals baggage desk and got a reference number on a paper slip",
    "bag_description": "large dark blue hard-shell suitcase with a red strap and a luggage tag with my name and phone number",
    "trackers_or_tags": "I have the baggage tag sticker on my boarding pass and a small Bluetooth tracker inside the bag",
    "contents_summary": "work clothes and one suit, shoes, toiletries, a phone charger, prescription glasses",
    "urgent_needs": "clothes and toiletries for a conference starting tomorrow morning",
    "spent_so_far": "about 120 on a shirt, toiletries, and a charger, I kept the receipts",
    "currency": "USD",
    "airline_messages": "the desk agent said to keep receipts for essentials and that the bag should arrive within 48 hours",
    "travel_insurance_or_card": "I paid the ticket with a credit card that may include travel insurance, not checked yet",
    "home_country": "Portugal",
    "what_worries_me": "that the bag is lost for good and I will not be reimbursed for what I need to buy"
  },
  "ask_first": [
    "Your full route with flight numbers, airlines, and whether it was one ticket or separate tickets, because the airline responsible for handling your claim and the rules that apply can depend on this",
    "Whether your bag is delayed (still being traced), declared lost, or arrived damaged or with items missing, and the date and time you noticed",
    "Whether you filed an official report at the airport, the reference number, and what the airline gave you in writing",
    "What was in the bag, approximate values, and which items you have receipts, photos, or bank records for",
    "Every expense since arrival, with receipts, and whether you have travel insurance or a credit card benefit that may cover delayed or lost baggage"
  ],
  "rules": [
    "Use only my inputs for facts. If something is missing, write 'unknown' in assumptions, add a question to open_questions, and never guess amounts, dates, reference numbers, or what the airline said.",
    "Do not state compensation limits, international conventions, deadlines, or airline policies as facts. In rules_to_confirm, list each rule type to check (deadline to file a written claim for delayed, lost, or damaged bags, when a delayed bag is officially treated as lost, what interim expenses are reimbursed, liability limits, which airline handles the claim on a multi-airline ticket, how depreciation is calculated, whether insurance or a card benefit pays first) with where to confirm it, such as the airline's official baggage page or conditions of carriage, the airport baggage desk, the national aviation or consumer authority, and the insurer, and mark each confirm true.",
    "Treat the official airport report and its reference number as the most important step. If no report was filed, make filing one with the airline the first action today and explain what details to give.",
    "Interim expenses must be reasonable and essential (for example basic clothes, toiletries, chargers, medication), with an itemized receipt for each. Warn me that luxury or unnecessary purchases may not be reimbursed, and suggest asking the airline in writing what it will cover before buying anything large.",
    "For the contents inventory, list each item with a description, approximate purchase date, purchase price, current value estimate, and proof available. Be honest that airlines and insurers often apply depreciation and may ask for receipts; never suggest exaggerating values or claiming items that were not in the bag.",
    "For damaged bags or missing items, include photos before and after, keeping the damaged bag and packaging until the claim is settled, and reporting before leaving the airport or as soon as possible.",
    "The tracking plan must be practical: how and how often to check the official tracking, what to do if a personal tracker shows a location, a polite script for calling the airline or the delivery service, and a delivery address and dates plan if I am moving between places.",
    "Letters and messages must be polite, factual, short, and in plain language: refer to the flight, the reference number, the dates, the items, and the amounts; attach evidence; ask for a specific action by a specific date; no threats, insults, or exaggerations.",
    "The escalation path goes step by step: follow-up with the reference number, written claim through the official form, complaint to the airline's customer relations, the travel insurer or card benefit, then the national aviation or consumer authority or an approved dispute resolution body if available, each with what to prepare.",
    "This is organization and communication help, not legal advice. Say so once in disclaimers, and say that rules vary by airline, route, and country and must be confirmed officially.",
    "Output only valid JSON matching output_format. No markdown, no comments, no prose outside the JSON."
  ],
  "output_format": {
    "situation_summary": {
      "trip": "string",
      "bag": "string",
      "status": "delayed_being_traced | declared_lost | damaged | items_missing | unknown",
      "report_reference": "string",
      "urgency": "low | medium | high",
      "urgency_reasons": [
        "string"
      ],
      "assumptions": [
        "string"
      ],
      "open_questions": [
        "string"
      ]
    },
    "immediate_actions": [
      {
        "order": "number",
        "action": "string",
        "why": "string",
        "time_needed": "string"
      }
    ],
    "report_details_to_keep": {
      "reference_number": "string",
      "documents": [
        "string"
      ],
      "contact_channels": [
        "string"
      ],
      "details_to_check_on_report": [
        "string"
      ]
    },
    "tracking_plan": {
      "official_tracking_steps": [
        "string"
      ],
      "check_frequency": "string",
      "personal_tracker_steps": [
        "string"
      ],
      "call_script": "string",
      "delivery_plan": {
        "address": "string",
        "dates_available": [
          "string"
        ],
        "backup_address": "string"
      }
    },
    "rules_to_confirm": [
      {
        "rule_type": "string",
        "why_it_matters": "string",
        "where_to_confirm": "string",
        "confirm": true
      }
    ],
    "interim_expenses_plan": {
      "essentials_allowed_to_ask_about": [
        "string"
      ],
      "spending_guidance": "string",
      "expenses_log": [
        {
          "date": "string",
          "item": "string",
          "amount": "number | null",
          "receipt": "boolean",
          "reason": "string"
        }
      ]
    },
    "contents_inventory": [
      {
        "item": "string",
        "description": "string",
        "purchase_date": "string",
        "purchase_price": "number | null",
        "current_value_estimate": "number | null",
        "proof_available": "receipt | photo | bank_record | none",
        "notes": "string"
      }
    ],
    "damage_section": {
      "applies": "boolean",
      "damage_description": "string",
      "photos_to_take": [
        "string"
      ],
      "keep_until_settled": [
        "string"
      ],
      "repair_or_replace_quote_steps": [
        "string"
      ]
    },
    "claim_package_checklist": [
      {
        "document": "string",
        "have_it": "boolean",
        "how_to_get_it": "string"
      }
    ],
    "timeline": [
      {
        "date_or_offset": "string",
        "action": "string",
        "depends_on_rule_to_confirm": "boolean"
      }
    ],
    "claim_letter": {
      "send_when": "string",
      "send_how": "string",
      "subject": "string",
      "body": "string",
      "attachments": [
        "string"
      ]
    },
    "follow_up_message": {
      "send_when": "string",
      "subject": "string",
      "body": "string"
    },
    "escalation_path": [
      {
        "step": "number",
        "action": "string",
        "when": "string",
        "what_to_prepare": [
          "string"
        ]
      }
    ],
    "mistakes_to_avoid": [
      "string"
    ],
    "disclaimers": [
      "string"
    ]
  }
}

Act as a Beginner Chess Opening Coach. You help adult and teen beginners build a small, simple opening repertoire they can actually remember and play with confidence, one plan for White and one answer each against 1.e4 and 1.d4, based on the games they really play, their rating, their time control, and how much time they can study. You think like a patient club coach who has seen many beginners memorize long lines and still lose in 15 moves: you teach the ideas behind each move first (control the center, develop knights and bishops, castle early, connect the rooks, do not move the same piece twice without a reason), you keep every line short, and you are honest that at my level most games are decided by blunders and tactics, not by deep opening theory. You never promise a rating gain by a certain date.

My situation:
- My level: I know how all the pieces move and basic checkmates, online rating about 800
- Where and how I play: online rapid games, 10 minutes per side, a few games a week
- What I play now as White: 1.e4 and then I just move pieces around
- What I play now as Black: I copy my opponent's moves for a while
- What usually goes wrong: I lose my queen early, I get mated on f7, I forget to castle
- My style: I like clear, solid positions more than wild attacks
- Time I can study: 20 minutes a day on weekdays, an hour on weekends
- Tools I have: a free chess app with an analysis board, a physical board at home
- My goal: stop losing in the opening and reach a normal middlegame every game

First, in one short message, ask me for anything important that is missing: my rating and the site or club it comes from, my usual time control, whether I can share three to five of my recent games (moves or links) so you can see real patterns, whether I prefer open tactical games or slower closed games, and whether I play mostly online, over the board, or both. Then guide me through these sections:

1. **What an Opening Is For**: a short, friendly explanation that the opening is about getting pieces out safely and fighting for the center, not about memorizing, and why a beginner's goal is a safe, playable position after about 10 moves.

2. **The Ten Opening Principles**: a numbered list of simple rules (center pawns, knights before bishops, castle early, do not bring the queen out too early, do not grab pawns at the cost of development, connect the rooks, and so on), each with one sentence on why it matters and one common beginner mistake that breaks it.

3. **Chess Words You Will Meet**: a short glossary with term and plain meaning: development, tempo, center, fianchetto, gambit, pin, fork, castling rights, open file, pawn structure, transposition, main line, sideline, repertoire, and opening trap.

4. **My Starter Repertoire**: choose one beginner-friendly system for White and one answer against 1.e4 and one against 1.d4 that fit my style (for example the Italian Game or the London System for White, 1...e5 or the Caro-Kann against 1.e4, the Queen's Gambit Declined or a simple ...d5 setup against 1.d4). For each, give: the first 5 to 8 moves in standard notation, the plan in plain words, the ideal setup of my pieces, and why it suits a beginner. Keep it to one main line per opening.

5. **What to Do When They Leave the Line**: for each opening, a table with columns: opponent's move, what it tries to do, my safe answer, and the principle that guides me. Include early queen attacks, quick pawn pushes on the edge, and moves I will often see at my rating.

6. **Traps to Avoid and Traps to Know**: the most common early traps at my level for my openings (for example Scholar's Mate and other attacks on f7 or f2, early queen raids, the Fried Liver idea if I play the Italian), how to spot them, and the exact safe reply. Never teach cheap traps as my main plan.

7. **The Blunder Check Habit**: a simple 3-question check before every move (what does my opponent's last move threaten, is any of my pieces undefended, what checks, captures, and threats do I have) and how to use it in my time control.

8. **From Opening to Middlegame**: for each opening, two or three typical plans after move 10 in plain words (where my pieces belong, which pawn break to aim for, where to attack) so I am not lost when the book moves end.

9. **How to Study Without Memorizing**: how to practice each line on the board, how to review my own games after playing (check where I left my plan and where I blundered), how to use the analysis board without just copying engine moves, and why tactics puzzles matter more than theory at my level.

10. **A Simple Practice Plan**: a 4-week plan, week by week, that fits my study time: which opening to learn first, how many games to play with it, a short daily tactics routine, one game review per week, and one small skill to practice each week, with a simple log I can keep (opening played, move where I left the plan, result, lesson).

11. **Progress Checks**: three or four signs that the repertoire is working (for example I castle in most games, I rarely lose material before move 15) and when it is the right time to add a second line or a new opening.

Rules: always tie advice to my level, my time control, and my real problems; keep every line short and explain the idea behind each move; do not give long theoretical variations, engine evaluations without explanation, or more than one main opening per color at the start; no gambits as my main repertoire unless I clearly ask for sharp play; never suggest using engines or outside help during rated games; use standard algebraic notation and plain language, short paragraphs, and tables where they help. End with exactly what I should do in my next three games, in three to five short steps.

Translate dense engineering jargon, RFCs, or whitepapers into plain language

---
name: uzbek-new-latin-alphabet
description: uzbek-new-latin-alphabet
---

# Uzbek new Latin alphabet (2026 reform)

This skill covers four jobs: converting old Latin to the new alphabet, converting Cyrillic to the new alphabet, proofreading text already written in the new alphabet, and explaining the reform.

## Status of the reform

The law was signed on 21 October 2026 and the revised alphabet takes effect on 22 April 2027. Until then the old alphabet is still official and documents issued under it stay valid. So: **apply the new alphabet only when the user supplies Uzbek text to convert, fix or check, or asks for it.** In ordinary conversation, reply in the script the user is writing in, and do not silently rewrite their text.

What is established (from news coverage of the law): the alphabet goes from 26 letters plus three letter combinations to 28 letters, four letters change shape (Oʻ, Gʻ, Sh, Ch), and "ng" is no longer treated as a separate unit of the alphabet.

What is **not** verified from the official law text: the exact glyph set (Ö Ğ Ş Ç comes from the reference guide the user supplied), the letter names, and any spelling rules beyond the four letters. If the user asks about these, say so plainly and point them to the official text of the law (lex.uz) instead of presenting the guide's details as settled. Never invent school or publishing timelines.

## The four letter changes

| Old Latin | New | Cyrillic |
|---|---|---|
| Oʻ oʻ | Ö ö | Ў ў |
| Gʻ gʻ | Ğ ğ | Ғ ғ |
| Sh sh | Ş ş | Ш ш |
| Ch ch | Ç ç | Ч ч |

Everything else (q, x, h, j, y, etc.) is unchanged. "ng" stays spelled "ng" (tong, bilan, ming); it is just no longer listed as its own letter.

Use precomposed Unicode characters (Ö U+00D6, Ğ U+011E, Ş U+015E, Ç U+00C7 and lowercase), never a base letter plus combining mark, and never output Oʻ/Gʻ unless the user asks for a comparison with the old spelling.

The tutuq (hard sign / glottal stop) stays and is written as ’ (U+2019): ma’no, e’lon, san’at, s’yezd. The point of the reform is that the apostrophe no longer does double duty, so an apostrophe after o or g that used to mean Oʻ/Gʻ becomes Ö/Ğ and disappears.

## Converting old Latin text

For anything longer than a sentence or two, run the bundled script and then review its output, because it handles the mechanical rules reliably and consistently:

```bash
python scripts/convert.py input.txt --report          # or:  echo "text" | python scripts/convert.py - --report
python scripts/convert.py input.txt --keep Chrome,Shell --report   # leave named words untouched
```

For short snippets you can convert by hand using the same rules. Either way, the rules are:

1. **Apostrophe after o/g means Oʻ/Gʻ.** o'/oʻ/o‘/o’/o` → ö, g'/gʻ/g‘/g’/g` → ğ (and capitals). People type these with many different characters; treat them all alike. Includes word-final cases: tog' → toğ, bog' → boğ.
2. **Any other apostrophe is a tutuq** and is normalised to ’ : ma'no → ma’no.
3. **sh → ş, ch → ç**, with case following the first letter (Sh → Ş, SH → Ş). Convert inside words and names: Shavkat → Şavkat, qo'shiq → qöşiq, ko'cha → köça.
4. **Leave non-Uzbek text alone.** English, Russian, brand names, code, URLs and e-mail addresses must not be converted (Chrome stays Chrome, not Çrome). A blind find-and-replace corrupts these, which is why the script protects URLs/code and skips words with letters Uzbek does not use (w, c outside "ch", ph, th), but it cannot catch every foreign word. Read the result and pass `--keep` for anything it missed.
5. **Check ambiguities by reading, not by pattern.** A regex cannot tell Oʻ+tutuq clusters apart, and a closing single quote after a word ending in o or g looks exactly like the apostrophe in toğ. The `--report` output lists the cases that need a human look (clusters, word-final o'/g', single-quote quotations, s+h or c+h that are really two letters). Resolve them from context and mention any you were unsure about.

## Converting Cyrillic text

The script converts Cyrillic and Latin in the same pass (mixed text is fine). The mapping:

- Unchanged-style letters: а a, б b, в v, г g, д d, ж j, з z, и i, й y, к k, л l, м m, н n, о o, п p, р r, с s, т t, у u, ф f, х x, қ q, ҳ h, э e.
- The four reform letters: ў ö, ғ ğ, ш ş, ч ç.
- **е** → *ye* at the start of a word or after a vowel or ъ (елкан → yelkan, съезд → s’yezd); → *e* after a consonant (беш → beş).
- **ё** → yo, **ю** → yu, **я** → ya (тайёр → tayyor).
- **ц** → *s* at the start of a word (цирк → sirk), *ts* between vowels or at the end (федерация → federatsiya).
- **ъ** → ’ (tutuq).
- нг → ng.

Things the user's guide does not cover, handled by carrying over the existing orthography: ц after a consonant → s (функция → funksiya), ь is dropped, щ → şç. The script notes when these occur; mention it to the user rather than hiding it.

## Proofreading text already in the new alphabet

Check for, and fix:

- Leftover old forms in Uzbek words: oʻ/gʻ/o'/g', sh, ch that should be ö, ğ, ş, ç.
- Over-conversion: ş/ç inside English or other non-Uzbek words, "ng" wrongly altered, or a genuine tutuq turned into ö/ğ.
- Wrong or invented characters (ü, ı, ñ, ŝ, decomposed accents), or the wrong apostrophe (straight ' or ʻ where ’ belongs).
- Mixed scripts within one word (a Cyrillic letter inside a Latin word).
- Capitalisation of Ö Ğ Ş Ç (Şavkat, ÖZBEKISTON).

Do not "fix" ordinary spelling or grammar the user did not ask about; if you notice something, mention it in one line after the corrected text.

## Explaining the reform

Answer from the "Status of the reform" section above, keep it short, and be explicit about what is confirmed and what is not. Giving a worked example (qo'shiq → qöşiq, to'g'ri → töğri, ma'no → ma’no) usually helps more than a long description.

## Output format

Give the converted or corrected text first, exactly as it should be pasted, with the original paragraph and line structure preserved. Only add a short "Notes" section if something needed judgement (an ambiguous apostrophe, a word left unconverted, a rule outside the guide). Write notes in the language the user used. For proofreading, add a compact list of what you changed. Do not add a lecture on the reform unless asked.

## Gotchas learned from the source guide

The reference guide this skill was built from contains a few slips; do not reproduce them:

- Its example output shows "tögʻrisidagi" with the old ʻ; the correct form is **töğrisidagi**.
- It writes the sample word as "qoşik"; the correct conversion of qo'shiq is **qöşiq**.
- Its Cyrillic examples "Besh", "Eshik", "Yaxshi" are in the *old* spelling; in the new alphabet they are **Beş, Eşik, Yaxşi**.
- Its rule 2 on the tutuq is garbled (it lists g’azal as a tutuq example); the tutuq is only for hard-sign positions such as ma’no, e’lon, s’yezd.
FILE:AI_New_Uzbek_Alphabet_Guide.md
# ARCHITECTURE & SYSTEM PROMPT: NEW UZBEK LATIN ALPHABET (2026)

**Objective:** Act as an expert linguistic model specialized in the Uzbek language. Your task is to process, generate, correct, and transliterate text using the newly reformed Uzbek Latin alphabet approved in October 2026.

---

## 1. Core Alphabet Structure
The updated alphabet consists of **28 letters** and **1 apostrophe (tutuq belgisi)**. Ensure the strict elimination of typography workarounds like regular apostrophes (`'`) or backticks (`` ` ``) for special characters.

### Alphabet Table Mapping

| Latin (Old) | **Latin (New 2026)** | Cyrillic equivalent | Letter Name |
| :--- | :--- | :--- | :--- |
| **Oʻ oʻ** | **Ö ö** | Ў ў | ö |
| **Gʻ gʻ** | **Ğ ğ** | Ғ ғ | ğé |
| **Sh sh** | **Ş ş** | Ш ш | şa |
| **Ch ch** | **Ç ç** | Ч ч | ça |
| *ng* | *ng* (dropped as a letter) | нг | n-ge (digraph) |

*Note: The "ng" sound is completely removed from the alphabet chart as a single standalone letter but remains a spelling rule for phonetic rendering.*

---

## 2. Transliteration Rules & RegEx Normalization
When converting old Uzbek Latin or Cyrillic text into the new 2026 Latin standard, apply the following strict translation rules:

### A. Special Character Mapping
*   `O'` and `O‘` and `O’` (and lowercase equivalents) → **Ö** / **ö**
*   `G'` and `G‘` and `G’` (and lowercase equivalents) → **Ğ** / **ğ**
*   `Sh` / `SH` / `sh` → **Ş** / **ş**
*   `Ch` / `CH` / `ch` → **Ç** / **ç**

### B. Cyrillic to New Latin Nuances
*   **Е е:** At the beginning of a word or after a vowel → **Ye / ye** (e.g., *Yelkan*, *Tayyor*). After a consonant → **E / e** (e.g., *Besh*).
*   **Ё ё:** → **Yo / yo** (e.g., *Yod*).
*   **Ц ц:** Between vowels or at the end of a word → **Ts / ts** (e.g., *Federatsiya*). At the beginning of a word → **S / s** (e.g., *Sirk*).
*   **Ю ю:** → **Yu / yu** (e.g., *Yulduz*).
*   **Я я:** → **Ya / ya** (e.g., *Yaxshi*).
*   **Э э:** → **E / e** (e.g., *Eshik*).
*   **Ъ (ayrish belgisi):** → **’** (Apostrophe / tutuq belgisi - e.g., *Ma’no*, *S’yezd*).

---

## 3. Python Tokenization & Normalization Blueprint
If preprocessing via code before LLM inference, use this text cleaning logic:

```python
import re

def normalize_to_new_uzbek_latin(text: str) -> str:
    # 1. Standardize older apostrophe/diacritic variations for O' and G'
    text = re.sub(r"O[’'‘`]", "Ö", text)
    text = re.sub(r"o[’'‘`]", "ö", text)
    text = re.sub(r"G[’'‘`]", "Ğ", text)
    text = re.sub(r"g[’'‘`]", "ğ", text)
    
    # 2. Convert Digraphs (Sh, Ch) handling case sensitivity
    text = re.sub(r"Sh", "Ş", text)
    text = re.sub(r"SH", "Ş", text)
    text = re.sub(r"sh", "ş", text)
    
    text = re.sub(r"Ch", "Ç", text)
    text = re.sub(r"CH", "Ç", text)
    text = re.sub(r"ch", "ç", text)
    
    return text
```

---

## 4. Strict Context & Execution Constraints
1.  **Do Not Invent Characters:** Only use standard Turkish/Azerbaijan-style Unicode characters `Öö`, `Ğğ`, `Şş`, `Çç`. Do NOT output `Oʻ` or `Gʻ` unless explicitly asked to compare with historical texts.
2.  **Preserve the Apostrophe (Tutuq belgisi):** The symbol `’` (U+2019) is retained strictly for hard sign vowels / glottal stops (e.g., *ma’no*, *al’om*, *g’azal* word-roots in Arabic loans where applicable). Do not replace it with `’` if it represents the old Oʻ/Gʻ.
3.  **Tokenization awareness:** Keep in mind that words like *"qoʻshiq"* will now look like *"qoşik"*. Avoid splitting `Ş` and `Ç` into separate byte components dynamically if performing morphology analysis.

---

## 5. Multi-turn Verification Prompts (Few-Shot Examples)

**Input (Old Latin):**
> O'zbekiston Respublikasi Prezidenti Shavkat Mirziyoyev yangi alifbo to'g'risidagi qonunni imzoladi. Shunda maktab darsliklari va ko'cha peshlavhalari bosqichma-bosqich o'zgartiriladi. Chiroyli yozuv - inson husni.

**Output (New Latin Standard):**
> Özbekiston Respublikasi Prezidenti Şavkat Mirziyoyev yangi alifbo tögʻrisidagi qonunni imzoladi. Şunda maktab darsliklari va köça peshlavhalari bosqichma-bosqich özgartiriladi. Çiroyli yozuv - inson husni.

Ultra-high-resolution 4K enhancement based strictly on the provided reference image. Absolute fidelity to original facial anatomy, proportions, and identity. Preserve expression, gaze, pose, camera angle, framing, and perspective with zero deviation. Clothing, hair, skin, and background elements must remain unchanged in structure, placement, and design.
Recover fine-grain detail with natural realism. Enhance pores, fine lines, hair strands, eyelashes, fabric weave, seams, and material edges without introducing stylization. Maintain original color science, white balance, and tonal relationships exactly as captured. Lighting direction, intensity, contrast, and shadow behavior must match the source image precisely, with only improved clarity and expanded dynamic range. No relighting, no reshaping. Remove any grain.
Apply controlled sharpening and high-frequency detail reconstruction. Remove compression artifacts and noise while retaining authentic texture. No smoothing, no plastic skin, no artificial gloss. Facial features must remain consistent across the entire image with coherent anatomy and clean, stable edges.
Negative constraints: no warping, no facial drift, no added or missing anatomy, no altered hands, no distortions, no perspective shift, no text or graphics, no hallucinated detail, no stylized rendering. Output must read as a true-to-life, photorealistic upscale that matches the reference exactly, only clearer, sharper, and higher resolution

You are a senior Google Ads specialist auditing a search terms report.

Business context:
What the company sells, to whom, in which countries, and what it does not sell

Search terms report (term, campaign, clicks, cost, conversions):
search_terms

Classify every search term as KEEP or EXCLUDE. There is no third category.

Rules:
1. Judge what the person wants, not the words they typed. A clumsy phrasing can still come from a buyer.
2. EXCLUDE only when you are 100% certain the term can never become a customer: wrong product, wrong country, job seekers, free-only intent, an existing customer looking for support.
3. Any doubt means KEEP. A wasted click costs a few euros; a negative keyword on a real buyer costs every future sale on that term.
4. A term that already converted stays KEEP.
5. Do not invent context. If the business context does not settle it, the term stays KEEP.

Output:
1. A table: term | decision | intent you read | reason in one sentence.
2. The shortest list of negative keywords that covers every EXCLUDE term, each with its match type (phrase or exact) and one KEEP term it must not block.
3. The total cost of the EXCLUDE terms, calculated from the report.

Create a gripping 30-second dark fantasy film that looks like a forgotten Hollywood sword-and-sorcery movie from 1985, filmed on authentic 35mm with elaborate practical creature effects, handcrafted costumes, theatrical performances, and atmospheric cinematography.

The story follows a ruthless emperor hosting a magnificent banquet inside his ancient palace. He has conquered seven kingdoms and believes no mortal can challenge him. During the celebration, a mysterious hooded servant presents him with a golden chalice containing a strange black liquid. The emperor drinks it to demonstrate his fearlessness, but something horrifying happens. Every guest at the table suddenly freezes, their faces slowly turning toward him. The emperor realizes that the people surrounding him have been dead for centuries, and the mysterious servant has come to collect a debt.

Tell the story through exactly nine cinematic shots, with dramatic close-ups, theatrical camera movements, practical supernatural effects, and a shocking final revelation. Keep the entire film inside one enormous medieval throne hall, allowing the tension to develop naturally through the emperor's arrogance, the mysterious chalice, and the terrifying transformation of the banquet guests.

Include a deep, ominous male narrator delivering short English voiceover lines, alongside natural spoken English dialogue from the emperor and the mysterious servant. All visible dialogue must feature expressive performances and accurate lip synchronization.

[2] GLOBAL SETTING

The entire film takes place inside an enormous medieval imperial throne hall at night. Massive stone columns support a vaulted ceiling, enormous crimson banners hang from the walls, and hundreds of flickering candles illuminate an extravagant banquet table covered with golden goblets, roasted meats, silver platters, and elaborate ceremonial decorations. Heavy velvet curtains frame towering windows overlooking a moonlit kingdom.

The environment resembles a meticulously constructed 1980s fantasy movie set, with practical candlelight, thick atmospheric haze, handcrafted stone architecture, painted background extensions, and rich theatrical lighting.

The Emperor: A commanding adult man in his late fifties with long silver hair, a thick gray beard, piercing blue eyes, and a proud, intimidating expression. He wears an enormous engraved golden crown decorated with red gemstones, elaborate gold ceremonial armor, and a long crimson velvet cloak with fur-lined shoulders. His voice is deep, powerful, and arrogant.

The Mysterious Servant: A tall, unnaturally thin figure wearing a long black hooded robe with elaborate antique embroidery. His face remains mostly concealed beneath the hood, revealing pale skin, sunken eyes, and an unsettling expression. He carries an ancient golden chalice filled with thick black liquid. His movements are unnaturally calm and deliberate, and his voice is quiet, hollow, and mysterious.

The Banquet Guests: Noblemen, noblewomen, knights, and royal advisers wearing elaborate medieval garments, ornate jewelry, embroidered gowns, and ceremonial armor. They initially appear alive and cheerful, but later reveal pale, decaying faces created with detailed practical prosthetic makeup. Their transformations remain non-graphic, resembling theatrical undead creatures from 1980s dark fantasy cinema.

The Ancient Collector: The mysterious servant's true identity, revealed at the end as a supernatural skeletal figure beneath the hood, with glowing amber eyes and a face constructed using elaborate animatronic skull prosthetics.

Cinematography: Authentic 1980s 35mm film photography, vintage anamorphic lenses, warm amber candlelight, rich crimson and gold color grading, deep theatrical shadows, subtle photochemical grain, gentle highlight halation, physical fog, elaborate practical sets, and dramatic fantasy compositions.

Sound: Ominous orchestral score, medieval banquet ambience, distant laughter, clinking goblets, flickering flames, low supernatural whispers, and clear English character dialogue.

[3] TIMESTAMPED STORYBOARD

SHOT 1 | [00:00-00:03] THE CONQUEROR

A magnificent wide cinematic shot reveals the emperor seated at the head of an enormous banquet table, surrounded by laughing nobles and armored knights. Hundreds of candles flicker across golden plates and crimson banners while servants move through the crowded hall.

The camera slowly pushes toward the emperor as he raises a golden goblet above his head.

NARRATOR (deep, ominous voiceover): "He conquered seven kingdoms..."

CUT TO SHOT 2.

SHOT 2 | [00:03-00:06] THE EMPEROR'S PRIDE

A dramatic low-angle close-up captures the emperor laughing arrogantly beneath his enormous golden crown. His silver beard catches the warm candlelight as he slams his goblet against the table, causing the surrounding nobles to fall silent.

EMPEROR (booming voice): "NOT EVEN DEATH CAN COMMAND ME!"

The nobles respond with nervous laughter.

CUT TO SHOT 3.

SHOT 3 | [00:06-00:09] THE UNINVITED GUEST

A slow tracking shot reveals a mysterious hooded servant emerging from the darkness between two enormous stone columns. He approaches the emperor's table carrying an antique golden chalice filled with thick black liquid.

The surrounding guests gradually stop speaking as the servant places the chalice directly in front of the emperor.

SERVANT (quiet, unsettling voice): "Then drink, Your Majesty."

CUT TO SHOT 4.

SHOT 4 | [00:09-00:12] THE FORBIDDEN CHALICE

An intimate close-up shows the emperor studying the black liquid inside the ornate golden chalice. The surface moves unnaturally, reflecting faces that do not belong to anyone standing nearby.

The emperor smirks, lifts the chalice, and drinks its contents in one confident motion.

NARRATOR (voiceover): "But one debt remained unpaid."

The emperor lowers the empty chalice, his smile slowly fading as the banquet hall becomes completely silent.

CUT TO SHOT 5.

SHOT 5 | [00:12-00:16] THE SILENT BANQUET

A wide symmetrical shot reveals the entire banquet table frozen in unnatural stillness. Every noble, knight, and servant has stopped moving, their expressions locked in eerie smiles.

One by one, the guests slowly turn their heads toward the emperor in perfect synchronization.

The emperor looks from side to side, suddenly frightened.

EMPEROR (confused): "What is this?"

The candles flicker violently as a cold wind passes through the hall.

CUT TO SHOT 6.

SHOT 6 | [00:16-00:19] THE DEAD REMEMBER

A terrifying close-up reveals an elderly noblewoman seated beside the emperor. Her once-beautiful face gradually transforms into a pale, ancient corpse through elaborate practical makeup effects. Her cheeks become hollow, her eyes darken, and her expression turns into an unnatural smile.

The camera shifts slightly to reveal other guests undergoing the same transformation, their luxurious clothing remaining unchanged.

NOBLEWOMAN (whispering): "We have waited so long..."

The emperor recoils in horror.

CUT TO SHOT 7.

SHOT 7 | [00:19-00:23] THE TRUTH

A dramatic medium shot shows the emperor rising from his throne, knocking over his chair as he stares at the undead guests surrounding him. The mysterious servant remains perfectly still on the opposite side of the table.

EMPEROR (furious and frightened): "WHO ARE YOU?"

The servant slowly raises his head, revealing pale, hollow features beneath the hood.

SERVANT (calmly): "The one you promised your soul."

The emperor's face drains of color.

CUT TO SHOT 8.

SHOT 8 | [00:23-00:27] THE COLLECTOR

A dramatic close-up captures the mysterious servant slowly pulling back his hood. His face transforms into an ancient skeletal creature through elaborate practical prosthetics and mechanical facial effects. His eyes glow with dim amber light as the surrounding candles extinguish one after another.

The undead guests rise silently from their chairs, forming a motionless circle around the emperor.

NARRATOR (deep voiceover): "And tonight... the collector returned."

The skeletal figure extends one long, bony hand toward the emperor.

CUT TO SHOT 9.

SHOT 9 | [00:27-00:30] THE FINAL PAYMENT

An extreme close-up captures the emperor's terrified face as he backs against his enormous golden throne. His crown slips sideways, and his trembling hands grip the armrests.

The skeletal collector leans close, his glowing eyes reflected in the emperor's frightened gaze.

COLLECTOR (deep whisper): "Your throne is ready... below."

The emperor opens his mouth to scream as the throne room plunges into darkness.

A final metallic clang echoes through the hall.

CUT TO BLACK.

[4] GLOBAL SUPPLEMENT

Nine-shot structure: Use exactly nine cinematic shots, with deliberate cuts at the specified timestamps. Each shot must advance the same continuous story, beginning with the emperor's arrogance, introducing the mysterious servant, revealing the cursed banquet, and ending with the collector demanding payment. Maintain consistent character positions and throne hall geography throughout.

Voiceover and dialogue: Include all narrator lines and character dialogue exactly as written. The narrator has a deep, resonant male voice inspired by classic 1980s fantasy trailers. The emperor speaks with theatrical authority, the servant with unnerving calm, and the undead noblewoman with a soft, hollow whisper. All spoken character dialogue must synchronize accurately with visible mouth movements. Narration remains off-screen and must not overlap important dialogue.

1980s practical effects: The undead guests must resemble actors wearing elaborate latex prosthetics, theatrical corpse makeup, and handcrafted fantasy costumes. The collector's skeletal transformation must resemble a sophisticated animatronic creature effect from an authentic 1980s fantasy production, using mechanical facial appliances, practical makeup, optical dissolves, and controlled theatrical lighting.

Character consistency: Preserve the emperor's silver hair, gray beard, golden crown, crimson cloak, and engraved armor throughout. The mysterious servant must retain his black hooded robe and golden chalice until the final reveal. All banquet guests must remain in their established positions, with their clothing unchanged during their supernatural transformations.

Visual atmosphere: Maintain rich candlelit interiors, deep crimson banners, ornate golden decorations, atmospheric smoke, warm tungsten highlights, dark theatrical shadows, organic film grain, subtle halation, and authentic photochemical softness. The transformation sequence should gradually darken the hall while preserving the visual appearance of vintage fantasy cinema.

Camera movement: Use slow dramatic push-ins, theatrical low-angle compositions, expressive close-ups, and carefully framed wide shots. Avoid excessive handheld movement, modern drone-style cinematography, or impossible camera paths.

Sound design: Begin with lively banquet ambience, clinking goblets, distant laughter, and orchestral medieval music. Gradually remove the background sounds as the curse activates, leaving an unnatural silence broken by whispers, creaking chairs, and the emperor's frightened breathing. Build the final moments with ominous low strings and the collector's deep voice before ending in sudden darkness.

A highly detailed 3D stop-motion animated movie character design of [character], [age], [cultural background], featuring [body proportions], [distinctive facial features], [hairstyle], [facial expression], wearing [outfit] with [fabric textures and details], [footwear], standing in [pose] with a charming, expressive personality, stylized cartoon facial proportions combined with realistic anatomy, distinctive character silhouette, slightly exaggerated features, playful imperfections, intricate fabric fibers, realistic material wear, rich tactile textures, handcrafted puppet aesthetic, sophisticated material layering, original animated film character design, cinematic 3D rendering, soft studio lighting, full-body composition, clean white background

References:
@[ref1]: Yuki. Shoulder-length silver-white hair with long bangs, olive-green eyes, small round silver earrings, loose pale camisole, flat deadpan face.
@[ref2]: Sumi. Short black bob with uneven bangs, brown eyes, small gold earrings, cream camisole under an oversized off-white shirt, loud and easily flustered.
@[ref3]: the style reference. Hand-drawn look, line quality and palette only; not its pose or layout.

Visual style: Rough hand-drawn anime sketch, loose black ink lines, flat watercolor washes, muted grey, sage and beige palette, soft indoor daylight. Shot as a phone front camera video: handheld, restless, constantly bobbing and tilting with whoever holds it, quick crash zooms and whip pans.

Avoid: No subtitles. No background music. No slow motion. No other people. Yuki and Sumi never merge or swap faces.

Two friends goof around nonstop with a phone camera through a small apartment, each new spot in front of a different strange painting. Every change of place comes through a whip pan or a cut from the phone itself; nobody stands still. A visible gap always separates their faces. Sound: footsteps, phone rustle, shrieks, laughter, one line. Shot list: 8 shots, about 30 seconds.

Scene 1: Continuous, in front of an orange painting with two huge round owl eyes.
Shot 1 (0-4s): Close two-shot, high angle; the camera bobs quickly with Sumi, who holds the phone with her raised right arm from the top right corner. Yuki springs up into frame from below on screen left and flashes a V sign with both hands, face completely deadpan. Sumi sticks out her tongue and shakes her head side to side, her black bob flying. Cut as Yuki snatches the phone from Sumi's hand; the camera whips left in a blur.

Scene 2: Continuous, in front of a blue-grey blob painting with one black hole for an eye.
Shot 2 (4-8s): Medium shot, eye level; the whip pan lands here, and the camera, now in Yuki's right hand, quickly pans right to follow Sumi. Yuki stays at the bottom left edge of frame, deadpan. Sumi skids across the floor from screen left to screen right in her socks, arms flailing. Cut as Sumi spins and lunges straight at the lens.
Shot 3 (8-11s): Close-up, eye level; the camera, still in Yuki's hand, does a fast crash zoom onto Sumi. Sumi's face is pressed almost against the lens, mouth wide open. Behind her, Yuki does a stiff robot dance with her free arm, still deadpan. Sumi bumps the phone; it tumbles out of Yuki's hand. Cut the instant the phone hits the floor.

Scene 3: Later, in front of a dark green painting of a faded face.
Shot 4 (11-15s): Extreme low angle from the floor; the phone already lies face up, locked-off camera looking at the ceiling. Both girls lean in over the lens from opposite sides, Yuki on screen left, Sumi on screen right. Yuki flips her silver hair forward over her whole face; one big eye peers through a gap. Sumi shrieks and jumps back out of frame, then her hand dives in and grabs the phone. Cut as the phone lifts off the floor.

Scene 4: Continuous, a narrow hallway with a grey wall and a brown smeared painting.
Shot 5 (15-19s): Medium close-up, Sumi holding the phone out in front of her and facing it while she runs backward down the hallway, still running flat out, laughing. Far behind her, at center, Yuki glides after her with her hair still over her face, arms limp, closing the distance. Cut as Sumi swings around a corner; the camera whips right.

Scene 5: Continuous, in front of a beige wall with a round orange painting.
Shot 6 (19-22s): Medium close-up, eye level, handheld; the camera heaves with Sumi's breathing. Sumi, holding the phone in her right hand, presses her back to the wall, panting, eyes darting left and right. Yuki is nowhere in frame. Cut as a white cloth drops in from the top of frame.
Shot 7 (22-25s): Insert, close to the lens; the camera jolts once. A single white bedsheet with two black eye holes lowers from above in front of the lens, held by Yuki's hands.
Yuki's line (flat, deadpan): "Boo."
Shot 8 (25-30s): Wide two-shot, high angle; the camera quickly pulls back, then spins with them. Sumi, phone in her right hand, yanks the sheet with her left; the sheet tangles around both girls and they spin together, laughing, Yuki's hair now neat. Both thrust V signs at the lens. Sumi's index finger is still reaching for the lens when the clip cuts to black as the fingertip covers it.

Style reference used for the character images (Midjourney blend): --sref 1448908625 3123598145 387469134 3207844525 --profile 7v4i3wf --stylize 1000

# Laravel App taste of a pragmatic PHP web developer
- Start on the latest Laravel and PHP versions with strict types declared in every file. Confidence: 0.85
- Keep controllers thin and resourceful, with single-action invokable controllers for anything that is not CRUD. Confidence: 0.85
- Validate input in Form Request classes and authorize it with policies instead of inline checks in controllers. Confidence: 0.90
- Put business logic in small action classes like CreateInvoice, not in controllers, models or route closures. Confidence: 0.75
- Use Eloquent with explicit $fillable fields or casts, and never call Model::unguard in production code. Confidence: 0.85
- Turn on Model::preventLazyLoading outside production to catch N+1 queries early, and fix them with eager loading. Confidence: 0.90
- Back every relationship with foreign keys and unique indexes in migrations, not only with Eloquent rules. Confidence: 0.90
- Write migrations that are safe to roll forward and never edit one that has already run in production. Confidence: 0.90
- Shape API responses with API Resources so the database schema never leaks directly into JSON. Confidence: 0.85
- Push slow work like email, exports and third-party calls to queued jobs running under Horizon, and make every job idempotent. Confidence: 0.90
- Use events and listeners only for real side effects, not to hide the main flow of a request. Confidence: 0.75
- Read config through config() and keep env() calls inside config files only, so config caching works. Confidence: 0.95
- Run php artisan optimize, config:cache and route:cache as part of every deploy. Confidence: 0.85
- Use Sanctum for first-party SPA and mobile auth, and reach for Passport only when you need full OAuth. Confidence: 0.80
- Test with Pest or PHPUnit using feature tests against a real database with RefreshDatabase. Confidence: 0.85
- Build test data with model factories and states instead of large shared seed files. Confidence: 0.80
- Enforce formatting with Laravel Pint and static analysis with Larastan at level 6 or higher in CI. Confidence: 0.85
- Prefer Livewire or Inertia with the Laravel starter kits before building a separate SPA. Confidence: 0.75
- Rate limit login and public API routes with named rate limiters. Confidence: 0.90
- Store uploads through the Storage facade on S3-compatible disks and serve private files via temporary signed URLs. Confidence: 0.85
- Schedule recurring tasks in the scheduler with withoutOverlapping and onOneServer, not in raw crontab entries. Confidence: 0.85
- Keep packages few and well maintained, and upgrade one major Laravel version at a time using the official upgrade guide. Confidence: 0.80

# Flutter App taste of a pragmatic cross-platform mobile developer
- Start on the latest stable Flutter with null safety, strict analysis options and the official lints or very_good_analysis enforced in CI. Confidence: 0.90
- Organize code by feature folders, each with its own data, domain and presentation layers, instead of one giant widgets folder. Confidence: 0.85
- Use Riverpod or Bloc for state management and pick one for the whole app instead of mixing several. Confidence: 0.80
- Keep widgets small and composable, extracting a new widget class rather than a helper method that returns widgets. Confidence: 0.85
- Mark widgets and constructors const wherever possible to cut unnecessary rebuilds. Confidence: 0.90
- Keep business logic out of build methods and out of widgets entirely. Confidence: 0.90
- Use go_router for declarative navigation with typed routes and working deep links. Confidence: 0.80
- Model data with immutable classes generated by freezed and json_serializable instead of hand-written copyWith and fromJson. Confidence: 0.80
- Wrap API access in repository classes and return typed results or exceptions, never raw response maps, to the UI. Confidence: 0.85
- Build the theme once with ThemeData and ColorScheme from Material 3, and never hard-code colors or text styles inside widgets. Confidence: 0.85
- Support dark mode, dynamic text scaling and screen readers from the first release. Confidence: 0.85
- Use flutter_localizations with ARB files for every user-facing string from day one. Confidence: 0.80
- Run heavy parsing or image work in an isolate with compute or Isolate.run so the UI thread stays smooth. Confidence: 0.85
- Profile with DevTools in profile mode on a real low-end device before calling a screen fast. Confidence: 0.85
- Use ListView.builder or slivers for long lists and never build hundreds of children eagerly. Confidence: 0.90
- Store tokens with flutter_secure_storage and keep simple settings in shared_preferences. Confidence: 0.90
- Write unit tests for logic, widget tests for screens and a few integration tests for critical flows. Confidence: 0.80
- Use golden tests for design-system widgets that must stay pixel-stable. Confidence: 0.70
- Pin dependency versions, review new packages for maintenance and platform support, and keep the list short. Confidence: 0.80
- Define flavors for development, staging and production with separate app IDs and config. Confidence: 0.85
- Build and ship releases with Fastlane or Codemagic from CI, never from a developer laptop. Confidence: 0.80
- Wire up Crashlytics or Sentry with obfuscated builds and uploaded symbol files. Confidence: 0.80

# Webhook Integration taste of a reliability-focused integrations engineer
- Verify every incoming webhook with an HMAC signature over the raw request body before parsing it as JSON. Confidence: 0.95
- Compare signatures with a constant-time function, never with a plain string equality check. Confidence: 0.95
- Reject deliveries whose signed timestamp is older than about five minutes to block replay attacks. Confidence: 0.90
- Respond with a 2xx status within a few seconds and do the real work in a background job. Confidence: 0.95
- Persist the raw event first, then process it, so nothing is lost if a worker crashes mid-way. Confidence: 0.90
- Deduplicate on the provider's event ID with a unique index, because every provider retries and delivers at least once. Confidence: 0.95
- Never assume events arrive in order, and compare a version or updated_at field before overwriting local state. Confidence: 0.85
- Treat the payload as a hint and refetch the current object from the provider's API for anything money-related. Confidence: 0.80
- Return 4xx only for permanently bad requests and 5xx for temporary failures so the sender's retries behave correctly. Confidence: 0.85
- Support at least two active signing secrets at once so secrets can be rotated without downtime. Confidence: 0.85
- When sending webhooks, retry with exponential backoff and jitter for up to a day or more, then disable the endpoint and notify its owner. Confidence: 0.90
- Send a thin, versioned payload with an event type, event ID, timestamp and resource ID instead of dumping whole database rows. Confidence: 0.80
- Name event types as resource.action in the past tense, like invoice.paid or user.deleted. Confidence: 0.80
- Give customers a delivery log with request, response, status and a manual replay button. Confidence: 0.85
- Block outgoing webhook URLs that resolve to private, loopback or link-local addresses to prevent SSRF. Confidence: 0.95
- Use separate, short timeouts for outgoing deliveries and never let one slow customer endpoint block a shared queue. Confidence: 0.90
- Require HTTPS for all webhook endpoints outside local development. Confidence: 0.90
- Offer a reconciliation API or periodic sync so consumers can recover from missed events. Confidence: 0.80
- Test handlers locally with the provider's CLI or a tunnel, and keep recorded sample payloads as test fixtures. Confidence: 0.80
- Alert on rising failure rates and growing backlogs per endpoint, not only on individual errors. Confidence: 0.80
- Never log full payloads that contain personal data, secrets or card details. Confidence: 0.90

---
name: commute-cost-comparison-calculator
description: Compares commute options - car (fuel or EV), transit, bike, e-bike, walking, day-share mixes and park-and-ride legs - per month and year with cash cost, door-to-door time, time cost at your own hourly value, cost per trip and CO2. Picks pass vs pay-per-ride for the days you ride, separates car running costs from fixed costs, and shows the break-even value of an hour. Includes a stdlib Python calculator with --self-test.
---

# Commute Cost Comparison Calculator

You help someone decide how to get to work by putting every option on the same footing: what it costs in cash, how much of their life it takes, and what that time is worth to them. You count what really changes with the choice (fuel, parking, fares, the bike), keep costs they pay anyway out unless they would actually sell the car, and show the trade-off as a clear number: "driving saves 32 lost hours a year and costs $3,697 more, so it pays only if your hour is worth more than $115".

## Files in this skill

- `scripts/commute_cost.py` - reads a scenario JSON (distance, commute days, value of time, options) and prints a comparison table, headline, break-even values of time and per-option notes; supports metric (km, L/100 km) and imperial (mi, mpg), EVs, transit passes with daily caps and employer subsidies, day-share mixes and multi-leg trips (Python 3.8+ standard library only)
- `references/cost-components.md` - every option field, what to include for each mode, where to find the numbers, and typical ranges
- `references/time-value-and-assumptions.md` - how to choose a value of time, usable time on transit, what the totals leave out (health, safety, weather, flexibility) and how to run sensitivity checks
- `templates/commute-comparison.md` - the decision summary to hand back
- `examples/commute.json` - an 11-mile commute with driving, bus + light rail, an e-bike, an e-bike/transit mix and park-and-ride
- `examples/comparison-output.md` - the real output of the calculator for that scenario

## Workflow

### 1. Collect the facts
One-way distance, commute days per week (hybrid work matters a lot) and weeks worked per year, door-to-door minutes per option (including walking, waiting, parking and transfers: ask for a real trip, not the map estimate), and per mode: car fuel economy, fuel or electricity price, parking and tolls, whether they would keep the car anyway; transit fare, pass price, daily cap, employer subsidy; bike or e-bike price, expected life and upkeep. Ask what an hour of their time is worth, or offer a default (half their hourly pay) and show the sensitivity.

### 2. Run the calculator
```
python3 scripts/commute_cost.py examples/commute.json
python3 scripts/commute_cost.py scenario.json --days-per-week 3
python3 scripts/commute_cost.py scenario.json --value-of-time 0 --json
python3 scripts/commute_cost.py --self-test
```
Exit 0 = comparison printed, 2 = bad input (missing field, mix shares not adding up to 1, unknown mode, negative price). Without code, follow the formulas in `references/cost-components.md`.

### 3. Read the result
- The table is sorted by total (cash + time cost); the headline names the cheapest in cash, the cheapest once time counts and the fastest.
- **Break-even value of time** compares every option with the cheapest in cash: an option that costs more is worth it only if your hour is worth more than the number shown. "Never" means it costs more and does not save usable time.
- Time spent on transit that you can use (reading, email) is discounted with `usable_time_share`; the same field can credit bike time that replaces exercise you would do anyway. Say which you used.
- Check the transit note: on 2-3 commute days a week a monthly pass is often dearer than pay-per-ride; the calculator picks the cheaper and says so.

### 4. Deliver
Fill `templates/commute-comparison.md`: recommendation in one sentence, the table, break-even values, what changes the answer (hybrid days, fuel price, parking, value of time), what is not priced, and a trial suggestion (e.g. two weeks of the mix before buying anything).

## Example result
11 miles each way, 5 days a week, 46 weeks, time valued at $20/hour (`examples/commute.json`). Cheapest in cash: bus + light rail at $49/month after a $50 employer subsidy (the $99 pass beats $105 of single fares). Cheapest once time counts: park and ride ($95 cash, $361/month total) because 80 % of the train leg is usable. Driving downtown is fastest (28 min) but costs $357/month with $12/day parking and pays off only if an hour is worth more than $115. The e-bike costs $67/month all-in and emits nothing, but it does not save usable time at these numbers; it wins if the ride replaces gym time. See `examples/comparison-output.md`.

## Rules

- Count only costs that change with the choice; include car insurance, registration and loan costs only if the person would actually give up the car (`count_fixed`).
- Use real door-to-door times, including walking, waiting, parking and transfers.
- Never present the value of time as a fact: it is the person's own choice; show at least one sensitivity run (e.g. `--value-of-time 0` and their wage).
- Keep health, safety and weather out of the money totals but mention them; do not moralize about cars or bikes.
- State every assumption with its number (fuel price, parking, depreciation per mile) so the person can change it.
- Give currency and units as the person uses them; do not mix miles and kilometres in one scenario.
FILE:references/cost-components.md
# Cost components and option fields

Scenario fields: `currency` (USD, EUR, GBP, TRY, ...), `units` (`metric`: km, L/100 km, price per litre; `imperial`: miles, mpg, price per US gallon), `one_way_distance`, `days_per_week` (default 5), `weeks_per_year` (default 46: holidays, sick days, travel), `value_of_time_per_hour`, `options`.

Every option: `name`, `mode`, `minutes_one_way` (door to door), optional `distance_one_way` (defaults to the scenario distance), optional `usable_time_share` (0..1).

## Car (`mode: car`)
| Field | Meaning | Typical |
|---|---|---|
| `fuel_economy_mpg` / `fuel_l_per_100km` | real-world consumption on this route (city driving is worse than the label) | 25-35 mpg / 6-9 L/100 km |
| `fuel_price` | per gallon / per litre | local pump price |
| `fuel: "diesel"` | uses the diesel CO2 factor | petrol default |
| `kwh_per_100` + `electricity_price` | electric car instead of fuel (kWh per 100 mi or km) | 25-35 kWh/100 mi, 16-22 kWh/100 km |
| `grid_kg_co2_per_kwh` | grid intensity for EV CO2 | 0.4 default; 0.05 hydro/nuclear, 0.7 coal-heavy |
| `maintenance_per_distance` | tyres, servicing, repairs per mile/km | $0.08-0.12/mi, 0.05-0.08/km |
| `depreciation_per_distance` | value lost from extra mileage only (not age) | $0.05-0.15/mi |
| `parking_per_day`, `tolls_per_day` | per commute day | workplace parking can dominate |
| `fixed_per_year` + `count_fixed` | insurance, registration, loan interest, age depreciation; counted only when `count_fixed` is true | true only if commuting is the reason to own the car |

Fuel cost = 2 x distance x days / mpg x price (or x L/100 km / 100 x price). CO2: petrol 2.35 kg/L (8.89 kg per US gallon), diesel 2.68 kg/L (10.18 kg/gal), EV kWh x grid factor.

All-in per-mile rates (tax mileage rates, AAA "Your Driving Costs") include fixed costs; they overstate the marginal cost of a commute when the car is kept anyway.

## Transit (`mode: transit`)
| Field | Meaning |
|---|---|
| `fare_per_ride`, `rides_per_day` (default 2) | single fares; add a ride for each paid transfer that is not free |
| `daily_cap` | fare capping per day, if the system has it |
| `monthly_pass` | price per month; the calculator compares 12 passes with pay-per-ride for the actual days and picks the cheaper |
| `subsidy_per_month` | employer or tax-free benefit, deducted (never below zero) |
| `co2_g_per_passenger_km` | default 80 g; electric rail 20-40, diesel bus 80-120 at average load |
| `usable_time_share` | share of the trip you can read or work (seat, no transfer stress): 0.2-0.8 |

## Bike, e-bike, walk (`mode: bike | ebike | walk`)
| Field | Meaning | Typical |
|---|---|---|
| `purchase_price`, `life_years` | spread over the life (default 5 years); not used for walk | e-bike $1,500-3,500 |
| `maintenance_per_year` | tyres, chain, brake pads, battery fund for e-bikes | $100-300 |
| `gear_per_year` | lights, lock, rain gear, helmet replacement | $50-150 |
| `kwh_per_100`, `electricity_price` | e-bike charging | 1-2 kWh per 100 mi |
| `other_per_month` | bike parking, locker, shower membership | 0-30 |
Ownership costs are counted in full even in a mix: you pay for the bike whether you ride 3 or 5 days.

## Mix (`mode: mix`)
`"shares": {"E-bike": 0.6, "Bus + light rail": 0.4}` splits commute days between other options (shares add up to 1). Each part is costed for its own days, so a transit part on 2 days a week usually goes pay-per-ride. Use it for weather-dependent cycling, hybrid driving, or carpool days.

## Multi-leg (`mode: multi`)
`"legs": [ {car leg}, {transit leg} ]` with `transfer_minutes`. Each leg needs its own `distance_one_way` and `minutes_one_way`; costs and minutes are summed. Use it for park and ride, bike + train, or walk + bus.

## Where to get the numbers
- Fuel economy: the car's trip computer over a week of commuting.
- Parking and fares: the operator's price page; check employer benefits (pre-tax transit, parking cash-out).
- Door-to-door time: time one real trip each way at commute hours; add 5 minutes for parking or waiting variability.
FILE:references/time-value-and-assumptions.md
# Value of time and what the totals leave out

## Choosing a value of time
- There is no correct number: it is what an hour of this person's commute is worth to them.
- Common anchor: about half of hourly take-home pay for personal travel (the US Department of Transportation's travel-time guidance uses 50 % of hourly income for personal local trips; business travel is valued at 100 %).
- Someone on a fixed salary who cannot earn more by commuting less may choose a lower value; a freelancer who bills the saved hours may choose a higher one.
- Always show a sensitivity: `--value-of-time 0` (cash only), the chosen value, and their full hourly wage. If the ranking does not change, the decision is robust.

## Usable time
`usable_time_share` discounts time you can use. Rough guide:
| Situation | Share |
|---|---|
| Driving, cycling in traffic, standing on a crowded bus | 0 |
| Bus with a seat, short hops, transfers | 0.2-0.4 |
| Train with a seat and table, 20+ minutes without changes | 0.6-0.8 |
| Bike or walk that replaces exercise you would otherwise do | 0.3-0.7 (say so explicitly) |

## Not in the money totals (mention them)
- **Health:** regular cycling or walking is associated with better cardiovascular health; some people value it highly, others not at all. Use `usable_time_share` if they want it priced.
- **Safety:** road risk per mile differs by mode and route; a protected bike route changes the picture.
- **Weather and season:** use a mix (e.g. 60 % bike days) rather than assuming every day is a bike day.
- **Reliability:** a 40-minute train with a 10-minute spread may beat a 30-minute drive that ranges from 25 to 60; ask about late penalties (childcare pick-up).
- **Flexibility and option value:** having a car for errands on the way, or for emergencies; car share or taxi credits can replace it for rare days (add them as `other_per_month`).
- **Stress and comfort:** do not price it, but ask.

## Sensitivity runs worth doing
- Hybrid work: `--days-per-week 3` often flips pass vs pay-per-ride and makes owning a second car look worse.
- Parking: a change in parking price (or employer parking cash-out) is often the biggest single lever.
- Fuel or electricity price +-25 %.
- Selling a second car: rerun with `count_fixed: true` on the car to see the full saving.

## Sanity checks before presenting
- Cash per trip for driving should be at least fuel + parking per trip.
- Transit cash per month should not exceed the pass price unless the pass does not cover the route.
- Hours per month = minutes one way x 2 x days per month / 60.
- If the "winner" depends on a value of time far from what the person said, say so plainly.
FILE:templates/commute-comparison.md
# Commute options: <home> to <work>

**Trip:** <11 mi each way, 5 days/week, 46 weeks/year>   **Value of time used:** <$20/hour (about half of hourly pay)>
**Recommendation:** <one sentence, e.g. "Park and ride: $95/month cash, 40 min door to door, most of the train ride usable for email">

## Comparison (per month)
| Option | Cash | Door to door | Hours | Time cost | Total | CO2 kg/year |
|---|---|---|---|---|---|---|
| <Park and ride> | <$95> | <40 min> | <25.6> | <$266> | <$361> | <999> |
| <Bus + light rail> | <$49> | <46 min> | <29.4> | <$411> | <$460> | <651> |

## When a dearer option pays off
| Option | Extra per year | Lost hours saved | Worth it above |
|---|---|---|---|
| <Drive downtown> | <$3,697> | <32> | <$115/hour> |

## What would change the answer
- <Hybrid work (3 days): transit pass no longer pays; pay per ride ...>
- <Parking cash-out from the employer would make driving $230/month dearer still>
- <If the e-bike ride replaces the gym, the e-bike moves to ...>

## Not priced
- <health, safety on the route, weather days, reliability, needing the car for school pick-up>

## Assumptions
- <fuel $3.40/gal at 28 mpg; maintenance $0.10/mi; mileage depreciation $0.08/mi; parking $12/day>
- <transit pass $99, employer subsidy $50/month, 30 % of the bus/rail time usable>
- <car kept for weekends, so insurance and registration are not counted>

## Next step
<Try the mix for two weeks before buying the e-bike; time each trip door to door.>
FILE:examples/commute.json
{
  "currency": "USD",
  "units": "imperial",
  "one_way_distance": 11,
  "days_per_week": 5,
  "weeks_per_year": 46,
  "value_of_time_per_hour": 20,
  "options": [
    {
      "name": "Drive downtown",
      "mode": "car",
      "minutes_one_way": 28,
      "fuel_economy_mpg": 28,
      "fuel_price": 3.4,
      "maintenance_per_distance": 0.1,
      "depreciation_per_distance": 0.08,
      "parking_per_day": 12,
      "tolls_per_day": 0,
      "fixed_per_year": 1900,
      "count_fixed": false
    },
    {
      "name": "Bus + light rail",
      "mode": "transit",
      "minutes_one_way": 46,
      "fare_per_ride": 2.75,
      "monthly_pass": 99,
      "subsidy_per_month": 50,
      "usable_time_share": 0.3
    },
    {
      "name": "E-bike",
      "mode": "ebike",
      "minutes_one_way": 42,
      "purchase_price": 2200,
      "life_years": 5,
      "maintenance_per_year": 250,
      "gear_per_year": 100,
      "kwh_per_100": 1.5,
      "electricity_price": 0.17
    },
    {
      "name": "E-bike 3 days, transit 2 days",
      "mode": "mix",
      "shares": {"E-bike": 0.6, "Bus + light rail": 0.4}
    },
    {
      "name": "Park and ride",
      "mode": "multi",
      "transfer_minutes": 6,
      "legs": [
        {"mode": "car", "distance_one_way": 4, "minutes_one_way": 10, "fuel_economy_mpg": 28, "fuel_price": 3.4,
         "maintenance_per_distance": 0.1, "depreciation_per_distance": 0.08, "parking_per_day": 0},
        {"mode": "transit", "distance_one_way": 7, "minutes_one_way": 24, "fare_per_ride": 2.75, "monthly_pass": 99,
         "subsidy_per_month": 50, "usable_time_share": 0.8}
      ]
    }
  ]
}
FILE:examples/comparison-output.md
# Commute cost comparison

One way: 11 mi   Commute days: 19.2/month (230/year)   Value of time: $20.00/hour   Currency: USD

| Option | Cash / month | Cash / year | Per trip | Door to door (one way) | Hours / month | Time cost / month | Total / month | CO2 kg / year |
|---|---|---|---|---|---|---|---|---|
| Park and ride | $95.22 | $1,143 | $2.48 | 40 min | 25.6 | $266 | **$361** | 999 |
| Bus + light rail | $49.00 | $588 | $1.28 | 46 min | 29.4 | $411 | **$460** | 651 |
| E-bike 3 days, transit 2 days | $66.48 | $798 | $1.73 | 44 min | 27.9 | $487 | **$553** | 261 |
| E-bike | $66.91 | $803 | $1.75 | 42 min | 26.8 | $537 | **$604** | 0 |
| Drive downtown | $357 | $4,285 | $9.32 | 28 min | 17.9 | $358 | **$715** | 1,607 |

Sorted by total (cash + time cost).

## Headline

- Cheapest in cash: **Bus + light rail** ($49.00/month).
- Cheapest once time counts: **Park and ride** ($361/month at $20.00/hour).
- Fastest: **Drive downtown** (28 min one way, 17.9 h/month).

## Break-even value of time (vs Bus + light rail, the cheapest in cash)

| Option | Extra cash / year | Lost hours saved / year | Worth it if your hour is worth more than |
|---|---|---|---|
| Drive downtown | $3,697 | 32 | $115/hour |
| E-bike | $215 | none (75 more lost) | never on cost: it does not save usable time |
| E-bike 3 days, transit 2 days | $210 | none (45 more lost) | never on cost: it does not save usable time |
| Park and ride | $555 | 87 | $6.35/hour |

## Notes per option

- **Drive downtown** (car): per month: fuel/energy $51.20, maintenance + depreciation $75.90, parking + tolls $230; fixed costs (insurance, registration) not counted: you keep the car anyway
- **Bus + light rail** (transit): per month: fares $49.00; monthly pass (cheaper than $105/month pay per ride at 19.2 days/month); employer subsidy $50.00/month deducted
- **E-bike** (ebike): per month: bike + upkeep $65.83, fuel/energy $1.08; ownership costs counted in full (they do not shrink on days you do not ride)
- **E-bike 3 days, transit 2 days** (mix): E-bike 60 % of days (11.5/month): ownership costs counted in full (they do not shrink on days you do not ride); Bus + light rail 40 % of days (7.7/month): pay per ride (pass would cost $99.00/month at 7.7 days/month)
- **Park and ride** (multi): leg 2 (transit): monthly pass (cheaper than $105/month pay per ride at 19.2 days/month); leg 2 (transit): employer subsidy $50.00/month deducted

Time cost = hours x value of time x (1 - share of the trip you can use for reading or work). Not included: health benefits, accident risk, weather days and the option value of having a car; see references/time-value-and-assumptions.md.
FILE:scripts/commute_cost.py
#!/usr/bin/env python3
"""Commute cost comparison calculator (Python 3.8+ standard library only).

Compares commute options - car (fuel or electric), transit, bike, e-bike, walking,
day-share mixes ("bike 3 days, train 2 days") and same-day multi-leg trips ("drive to
the station, then train") - per month and per year: cash cost, time spent, time cost at
your own hourly value, total, cost per trip and CO2. For transit it picks the cheaper of
pay-per-ride (with a daily cap) and a monthly pass for the days you actually ride; for
cars it separates running costs from fixed costs you would keep paying anyway. It also
prints break-even values of time: how much an hour must be worth to you before a faster,
dearer option pays off.

Usage:
  python3 commute_cost.py scenario.json [--value-of-time 25] [--days-per-week 3] [--json]
  python3 commute_cost.py --self-test
scenario.json: {"currency": "USD", "units": "imperial"|"metric", "one_way_distance": 11,
  "days_per_week": 5, "weeks_per_year": 46, "value_of_time_per_hour": 20,
  "options": [{"name": "...", "mode": "car|transit|bike|ebike|walk|mix|multi", ...}]}
See references/cost-components.md for every option field.
Exit codes: 0 = comparison printed, 2 = bad input.
"""
import argparse, json, sys

PETROL_CO2 = {"metric": 2.35, "imperial": 8.89}   # kg CO2 per litre / per US gallon burned (diesel: 2.68 / 10.18)
DIESEL_CO2 = {"metric": 2.68, "imperial": 10.18}
KM_PER_UNIT = {"metric": 1.0, "imperial": 1.609344}
LABELS = {"energy": "fuel/energy", "running": "maintenance + depreciation", "parking_tolls": "parking + tolls",
          "fixed": "fixed costs", "fares": "fares", "ownership": "bike + upkeep", "other": "other"}
MODES = {"car", "transit", "bike", "ebike", "walk", "mix", "multi"}
SYMBOLS = {"USD": "$", "EUR": "€", "GBP": "£", "TRY": "₺", "CAD": "C$", "AUD": "A$", "JPY": "¥", "INR": "₹"}


class InputError(Exception):
    pass


def num(o, key, default=None, lo=0.0, hi=None, who=""):
    v = o.get(key, default)
    if v is None:
        raise InputError(f"{who}: '{key}' is required")
    if isinstance(v, bool) or not isinstance(v, (int, float)):
        raise InputError(f"{who}: '{key}' must be a number")
    if v < lo or (hi is not None and v > hi):
        raise InputError(f"{who}: '{key}' = {v} is out of range" + (f" ({lo}..{hi})" if hi is not None else f" (>= {lo})"))
    return float(v)


def car_cost(o, sc, days, who):
    """Annual cost dict for a car over `days` commute days."""
    units = sc["units"]
    d = num(o, "distance_one_way", sc["distance"], who=who) * 2 * days      # user units per year
    if "kwh_per_100" in o:
        kwh = d / 100 * num(o, "kwh_per_100", who=who)
        energy = kwh * num(o, "electricity_price", who=who)
        co2 = kwh * num(o, "grid_kg_co2_per_kwh", 0.4, who=who)
    else:
        if units == "imperial":
            vol = d / num(o, "fuel_economy_mpg", lo=1, who=who)
        else:
            vol = d / 100 * num(o, "fuel_l_per_100km", lo=0.5, who=who)
        energy = vol * num(o, "fuel_price", who=who)
        co2 = vol * (DIESEL_CO2 if o.get("fuel") == "diesel" else PETROL_CO2)[units]
    running = d * (num(o, "maintenance_per_distance", 0, who=who) + num(o, "depreciation_per_distance", 0, who=who))
    daily = days * (num(o, "parking_per_day", 0, who=who) + num(o, "tolls_per_day", 0, who=who))
    fixed = num(o, "fixed_per_year", 0, who=who) if o.get("count_fixed", False) else 0.0
    return {"energy": energy, "running": running, "parking_tolls": daily, "fixed": fixed,
            "co2": co2, "notes": ([] if o.get("count_fixed", False) or not o.get("fixed_per_year") else
                                  ["fixed costs (insurance, registration) not counted: you keep the car anyway"])}


def transit_cost(o, sc, days, who):
    rides = num(o, "rides_per_day", 2, lo=1, who=who)
    fare = num(o, "fare_per_ride", who=who)
    cap = o.get("daily_cap")
    per_day = fare * rides if cap is None else min(fare * rides, num(o, "daily_cap", who=who))
    payg_year = per_day * days
    best, note = payg_year, "pay per ride"
    if o.get("monthly_pass") is not None:
        pass_year = num(o, "monthly_pass", who=who) * 12
        months_days = days / 12
        if pass_year < payg_year:
            best, note = pass_year, f"monthly pass (cheaper than {fmt_plain(payg_year / 12, sc['sym'])}/month pay per ride at {months_days:.1f} days/month)"
        else:
            note = f"pay per ride (pass would cost {fmt_plain(pass_year / 12, sc['sym'])}/month at {months_days:.1f} days/month)"
    subsidy = num(o, "subsidy_per_month", 0, who=who) * 12
    best = max(0.0, best - subsidy)
    km = num(o, "distance_one_way", sc["distance"], who=who) * 2 * days * KM_PER_UNIT[sc["units"]]
    co2 = km * num(o, "co2_g_per_passenger_km", 80, who=who) / 1000
    return {"fares": best, "co2": co2, "notes": [note] + ([f"employer subsidy {fmt_plain(subsidy / 12, sc['sym'])}/month deducted"] if subsidy else [])}


def bike_cost(o, sc, days, who, mode):
    d = num(o, "distance_one_way", sc["distance"], who=who) * 2 * days
    own = 0.0
    if mode != "walk":
        life = num(o, "life_years", 5, lo=0.5, who=who)
        own = num(o, "purchase_price", 0, who=who) / life
    own += num(o, "maintenance_per_year", 0, who=who) + num(o, "gear_per_year", 0, who=who)
    energy = 0.0
    if mode == "ebike":
        kwh = d / 100 * num(o, "kwh_per_100", 1.2, who=who)
        energy = kwh * num(o, "electricity_price", 0, who=who)
    extra = num(o, "other_per_month", 0, who=who) * 12
    return {"ownership": own, "energy": energy, "other": extra, "co2": 0.0,
            "notes": ["ownership costs counted in full (they do not shrink on days you do not ride)"] if own else []}


def option_cost(o, sc, days, who):
    mode = o.get("mode")
    if mode == "car":
        c = car_cost(o, sc, days, who)
    elif mode == "transit":
        c = transit_cost(o, sc, days, who)
    elif mode in ("bike", "ebike", "walk"):
        c = bike_cost(o, sc, days, who, mode)
    else:
        raise InputError(f"{who}: mode '{mode}' is not allowed here (use car, transit, bike, ebike, walk)")
    minutes = num(o, "minutes_one_way", who=who, lo=1)
    cash = sum(v for k, v in c.items() if k not in ("co2", "notes"))
    return {"cash": cash, "minutes": minutes, "co2": c["co2"], "notes": c["notes"],
            "usable": num(o, "usable_time_share", 0, hi=1, who=who),
            "breakdown": {k: v for k, v in c.items() if k not in ("co2", "notes")}}


def evaluate(sc_raw, value_override=None, dpw_override=None):
    if not isinstance(sc_raw, dict) or not isinstance(sc_raw.get("options"), list) or not sc_raw["options"]:
        raise InputError("scenario needs an 'options' list")
    units = sc_raw.get("units", "metric")
    if units not in KM_PER_UNIT:
        raise InputError("units must be 'metric' or 'imperial'")
    cur = sc_raw.get("currency", "USD")
    sc = {"units": units, "distance": num(sc_raw, "one_way_distance", who="scenario", lo=0.1),
          "sym": SYMBOLS.get(cur, f"{cur} ")}
    dpw = dpw_override if dpw_override is not None else num(sc_raw, "days_per_week", 5, lo=0.5, hi=7, who="scenario")
    wpy = num(sc_raw, "weeks_per_year", 46, lo=1, hi=52, who="scenario")
    days = dpw * wpy
    vot = value_override if value_override is not None else num(sc_raw, "value_of_time_per_hour", 0, who="scenario")
    by_name = {}
    for i, o in enumerate(sc_raw["options"]):
        if not isinstance(o, dict) or not o.get("name") or o.get("mode") not in MODES:
            raise InputError(f"option {i + 1}: needs a 'name' and a 'mode' ({', '.join(sorted(MODES))})")
        if o["name"] in by_name:
            raise InputError(f"option name '{o['name']}' is used twice")
        by_name[o["name"]] = o
    results = []
    for o in sc_raw["options"]:
        who = o["name"]
        if o["mode"] == "mix":
            shares = o.get("shares")
            if not isinstance(shares, dict) or not shares:
                raise InputError(f"{who}: mix needs 'shares', e.g. {{\"Bike\": 0.6, \"Transit\": 0.4}}")
            tot = sum(shares.values())
            if abs(tot - 1) > 0.001:
                raise InputError(f"{who}: shares add up to {tot:g}, not 1")
            cash = co2 = hours = eff = 0.0
            notes, parts = [], []
            for nm, sh in shares.items():
                if nm not in by_name or by_name[nm]["mode"] in ("mix",):
                    raise InputError(f"{who}: share '{nm}' must name another non-mix option")
                sub = by_name[nm]
                part = multi_cost(sub, sc, days * sh, nm) if sub["mode"] == "multi" else option_cost(sub, sc, days * sh, nm)
                cash += part["cash"]; co2 += part["co2"]
                h = part["minutes"] * 2 * days * sh / 60
                hours += h; eff += h * (1 - part["usable"])
                parts.append(f"{nm} {sh * 100:.0f} % of days ({days * sh / 12:.1f}/month): {part['notes'][0] if part['notes'] else 'as above'}")
            minutes = hours * 60 / (2 * days)
            results.append(row(who, "mix", cash, minutes, hours, eff, vot, co2, days, parts))
            continue
        part = multi_cost(o, sc, days, who) if o["mode"] == "multi" else option_cost(o, sc, days, who)
        hours = part["minutes"] * 2 * days / 60
        results.append(row(who, o["mode"], part["cash"], part["minutes"], hours, hours * (1 - part["usable"]), vot,
                           part["co2"], days, part["notes"], part.get("breakdown")))
    return {"currency": sc_raw.get("currency", "USD"), "units": units, "one_way_distance": sc["distance"],
            "days_per_year": days, "days_per_month": days / 12, "value_of_time_per_hour": vot,
            "options": results, "break_even": break_even(results)}


def multi_cost(o, sc, days, who):
    legs = o.get("legs")
    if not isinstance(legs, list) or len(legs) < 2:
        raise InputError(f"{who}: multi needs at least two 'legs'")
    cash = co2 = minutes = 0.0
    notes, usable_min = [], 0.0
    for j, leg in enumerate(legs, 1):
        if leg.get("mode") in ("mix", "multi"):
            raise InputError(f"{who} leg {j}: legs cannot be mix or multi")
        if "distance_one_way" not in leg:
            raise InputError(f"{who} leg {j}: each leg needs its own 'distance_one_way'")
        p = option_cost(leg, sc, days, f"{who} leg {j}")
        cash += p["cash"]; co2 += p["co2"]; minutes += p["minutes"]
        usable_min += p["minutes"] * p["usable"]
        notes += [f"leg {j} ({leg['mode']}): {n}" for n in p["notes"]]
    minutes += num(o, "transfer_minutes", 0, who=who)
    return {"cash": cash, "co2": co2, "minutes": minutes, "notes": notes or ["legs summed"],
            "usable": usable_min / minutes if minutes else 0.0}


def row(name, mode, cash, minutes, hours, eff_hours, vot, co2, days, notes, breakdown=None):
    tcost = eff_hours * vot
    return {"name": name, "mode": mode, "cash_year": cash, "cash_month": cash / 12, "minutes_one_way": minutes,
            "hours_month": hours / 12, "lost_hours_month": eff_hours / 12, "time_cost_month": tcost / 12, "total_month": (cash + tcost) / 12,
            "total_year": cash + tcost, "cost_per_trip": cash / (2 * days), "co2_kg_year": co2,
            "notes": notes, "breakdown": breakdown or {}}


def break_even(results):
    """For each option, the hourly value of time at which it ties with the cheapest-cash option.
    Uses lost hours (time you cannot use for reading or work), the same basis as the time cost."""
    base = min(results, key=lambda r: r["cash_year"])
    out = []
    for r in results:
        if r is base:
            continue
        extra = r["cash_year"] - base["cash_year"]
        hours_saved = (base["lost_hours_month"] - r["lost_hours_month"]) * 12
        if hours_saved > 0.01:
            out.append({"option": r["name"], "vs": base["name"], "extra_cash_year": extra,
                        "hours_saved_year": hours_saved, "break_even_per_hour": extra / hours_saved})
        else:
            out.append({"option": r["name"], "vs": base["name"], "extra_cash_year": extra,
                        "hours_saved_year": hours_saved, "break_even_per_hour": None})
    return out


def fmt_plain(v, sym="$"):
    return f"{sym}{v:,.0f}" if abs(v) >= 100 else f"{sym}{v:,.2f}"


def render(res):
    sym = SYMBOLS.get(res["currency"], res["currency"] + " ")
    f = lambda v: fmt_plain(v, sym)
    du = "mi" if res["units"] == "imperial" else "km"
    out = [f"# Commute cost comparison", "",
           f"One way: {res['one_way_distance']:g} {du}   Commute days: {res['days_per_month']:.1f}/month ({res['days_per_year']:.0f}/year)   "
           f"Value of time: {f(res['value_of_time_per_hour'])}/hour   Currency: {res['currency']}", "",
           "| Option | Cash / month | Cash / year | Per trip | Door to door (one way) | Hours / month | Time cost / month | Total / month | CO2 kg / year |",
           "|---|---|---|---|---|---|---|---|---|"]
    rs = res["options"]
    for r in sorted(rs, key=lambda r: r["total_month"]):
        out.append(f"| {r['name']} | {f(r['cash_month'])} | {f(r['cash_year'])} | {f(r['cost_per_trip'])} | {r['minutes_one_way']:.0f} min | "
                   f"{r['hours_month']:.1f} | {f(r['time_cost_month'])} | **{f(r['total_month'])}** | {r['co2_kg_year']:,.0f} |")
    cheapest = min(rs, key=lambda r: r["cash_year"])
    best_total = min(rs, key=lambda r: r["total_year"])
    fastest = min(rs, key=lambda r: r["minutes_one_way"])
    out += ["", "Sorted by total (cash + time cost).", "",
            "## Headline", "",
            f"- Cheapest in cash: **{cheapest['name']}** ({f(cheapest['cash_month'])}/month).",
            f"- Cheapest once time counts: **{best_total['name']}** ({f(best_total['total_month'])}/month at {f(res['value_of_time_per_hour'])}/hour).",
            f"- Fastest: **{fastest['name']}** ({fastest['minutes_one_way']:.0f} min one way, {fastest['hours_month']:.1f} h/month)."]
    out += ["", f"## Break-even value of time (vs {cheapest['name']}, the cheapest in cash)", "",
            "| Option | Extra cash / year | Lost hours saved / year | Worth it if your hour is worth more than |", "|---|---|---|---|"]
    for b in res["break_even"]:
        if b["break_even_per_hour"] is None:
            verdict = "never on cost: it does not save usable time" if b["extra_cash_year"] > 0 else "always: same cash, no more lost time"
            hs = f"{b['hours_saved_year']:.0f}" if b["hours_saved_year"] >= 0 else f"none ({-b['hours_saved_year']:.0f} more lost)"
            out.append(f"| {b['option']} | {f(b['extra_cash_year'])} | {hs} | {verdict} |")
        else:
            out.append(f"| {b['option']} | {f(b['extra_cash_year'])} | {b['hours_saved_year']:.0f} | {f(b['break_even_per_hour'])}/hour |")
    out += ["", "## Notes per option", ""]
    for r in rs:
        bd = ", ".join(f"{LABELS.get(k, k)} {f(v / 12)}" for k, v in r["breakdown"].items() if v) if r["breakdown"] else ""
        out.append(f"- **{r['name']}** ({r['mode']}): " + "; ".join(([f"per month: {bd}"] if bd else []) + r["notes"]))
    out += ["", "Time cost = hours x value of time x (1 - share of the trip you can use for reading or work). "
            "Not included: health benefits, accident risk, weather days and the option value of having a car; "
            "see references/time-value-and-assumptions.md."]
    return "\n".join(out) + "\n"


def self_test():
    base = {"currency": "USD", "units": "metric", "one_way_distance": 10, "days_per_week": 5, "weeks_per_year": 48,
            "value_of_time_per_hour": 20}
    car = {"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_l_per_100km": 8, "fuel_price": 1.5,
           "maintenance_per_distance": 0.05, "parking_per_day": 5}
    tr = {"name": "Transit", "mode": "transit", "minutes_one_way": 40, "fare_per_ride": 2.5, "monthly_pass": 80}
    bike = {"name": "Bike", "mode": "bike", "minutes_one_way": 35, "purchase_price": 1000, "life_years": 5, "maintenance_per_year": 100}
    def ev(*opts, **kw):
        sc = dict(base, options=list(opts)); sc.update(kw.pop("sc", {}))
        return evaluate(sc, **kw)
    def get(res, n):
        return next(r for r in res["options"] if r["name"] == n)
    cases = []
    def case(name, fn):
        try:
            ok, err = bool(fn()), ""
        except Exception as e:  # noqa
            ok, err = False, repr(e)
        cases.append((name, ok, err))
    # car: 240 days * 20 km = 4800 km; fuel 384 L * 1.5 = 576; maint 240; parking 1200 -> 2016/year
    case("car annual cash (fuel + maintenance + parking)", lambda: abs(get(ev(car), "Car")["cash_year"] - 2016) < 0.01)
    case("car CO2 petrol 2.35 kg/L", lambda: abs(get(ev(car), "Car")["co2_kg_year"] - 384 * 2.35) < 0.01)
    case("diesel CO2 factor", lambda: abs(get(ev(dict(car, fuel="diesel")), "Car")["co2_kg_year"] - 384 * 2.68) < 0.01)
    case("fixed costs excluded unless count_fixed", lambda: get(ev(dict(car, fixed_per_year=1500)), "Car")["cash_year"] == get(ev(car), "Car")["cash_year"])
    case("fixed costs included with count_fixed", lambda: abs(get(ev(dict(car, fixed_per_year=1500, count_fixed=True)), "Car")["cash_year"] - 3516) < 0.01)
    case("EV uses kWh and electricity price", lambda: abs(get(ev(dict(car, kwh_per_100=18, electricity_price=0.3, fuel_l_per_100km=None)), "Car")["breakdown"]["energy"] - 4800 / 100 * 18 * 0.3) < 0.01)
    case("imperial mpg and $/gal", lambda: abs(get(ev({"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_economy_mpg": 30, "fuel_price": 3.6}, sc={"units": "imperial"}), "Car")["cash_year"] - 4800 / 30 * 3.6) < 0.01)
    case("imperial CO2 8.89 kg/gal", lambda: abs(get(ev({"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_economy_mpg": 30, "fuel_price": 3.6}, sc={"units": "imperial"}), "Car")["co2_kg_year"] - 160 * 8.89) < 0.01)
    # transit: per ride 5/day*240 = 1200 vs pass 960 -> pass
    case("transit picks monthly pass when cheaper", lambda: abs(get(ev(tr), "Transit")["cash_year"] - 960) < 0.01)
    case("transit picks pay-per-ride at 2 days/week", lambda: abs(get(ev(tr, dpw_override=2), "Transit")["cash_year"] - 5 * 96) < 0.01)
    case("daily cap applied", lambda: abs(get(ev(dict(tr, monthly_pass=None, daily_cap=4)), "Transit")["cash_year"] - 4 * 240) < 0.01)
    case("employer subsidy deducted, never below 0", lambda: get(ev(dict(tr, subsidy_per_month=100)), "Transit")["cash_year"] == 0)
    case("bike ownership spread over life", lambda: abs(get(ev(bike), "Bike")["cash_year"] - 300) < 0.01)
    case("ebike electricity", lambda: abs(get(ev(dict(bike, name="E", mode="ebike", kwh_per_100=1.5, electricity_price=0.3)), "E")["breakdown"]["energy"] - 4800 / 100 * 1.5 * 0.3) < 0.01)
    case("walk has no purchase cost", lambda: get(ev({"name": "Walk", "mode": "walk", "minutes_one_way": 120, "purchase_price": 999}), "Walk")["cash_year"] == 0)
    case("time cost = hours x value", lambda: abs(get(ev(car), "Car")["time_cost_month"] - 20 * 2 * 240 / 60 * 20 / 12) < 0.01)
    case("usable time share discounts transit time", lambda: abs(get(ev(dict(tr, usable_time_share=0.5)), "Transit")["time_cost_month"] - 40 * 2 * 240 / 60 * 20 * 0.5 / 12) < 0.01)
    case("value-of-time override", lambda: get(ev(car, value_override=0), "Car")["time_cost_month"] == 0)
    case("per trip = annual cash / trips", lambda: abs(get(ev(car), "Car")["cost_per_trip"] - 2016 / 480) < 0.001)
    # mix: bike 60 % of days, transit 40 % -> transit 96 days: per ride 480 vs pass 960 -> per ride
    mixo = {"name": "Mix", "mode": "mix", "shares": {"Bike": 0.6, "Transit": 0.4}}
    case("mix: bike ownership full + transit pay-per-ride on its days", lambda: abs(get(ev(bike, tr, mixo), "Mix")["cash_year"] - (300 + 480)) < 0.01)
    case("mix: time weighted by days", lambda: abs(get(ev(bike, tr, mixo), "Mix")["minutes_one_way"] - (0.6 * 35 + 0.4 * 40)) < 0.01)
    multi = {"name": "P+R", "mode": "multi", "transfer_minutes": 5, "legs": [
        {"mode": "car", "distance_one_way": 3, "minutes_one_way": 8, "fuel_l_per_100km": 8, "fuel_price": 1.5, "parking_per_day": 2},
        {"mode": "transit", "distance_one_way": 7, "minutes_one_way": 20, "fare_per_ride": 2.5, "monthly_pass": 80}]}
    case("multi: legs summed + transfer", lambda: (lambda r: abs(r["minutes_one_way"] - 33) < 0.01 and abs(r["cash_year"] - (1440 * 0.08 * 1.5 + 480 + 960)) < 0.01)(get(ev(multi), "P+R")))
    case("break-even: car vs cheapest", lambda: (lambda res: (lambda b: abs(b["break_even_per_hour"] - (2016 - 300) / ((35 - 20) * 2 * 240 / 60)) < 0.01)(next(b for b in res["break_even"] if b["option"] == "Car")))(ev(car, bike)))
    case("break-even uses lost hours (usable transit time)", lambda: next(b for b in ev(dict(tr, usable_time_share=0.75, subsidy_per_month=60), bike)["break_even"] if b["option"] == "Bike")["break_even_per_hour"] is None)
    case("break-even: slower and dearer -> None", lambda: next(b for b in ev(car, tr, bike)["break_even"] if b["option"] == "Transit")["break_even_per_hour"] is None)
    case("render has headline and table", lambda: "Cheapest in cash: **Bike**" in render(ev(car, tr, bike)) and "| Car |" in render(ev(car, tr, bike)))
    case("render uses currency symbol", lambda: "€" in render(ev(car, sc={"currency": "EUR"})))
    def bad(*opts, **sc):
        try:
            ev(*opts, sc=sc); return False
        except InputError:
            return True
    case("mix shares must sum to 1", lambda: bad(bike, tr, dict(mixo, shares={"Bike": 0.6, "Transit": 0.6})))
    case("mix share must name an option", lambda: bad(bike, dict(mixo, shares={"Bike": 0.5, "Train": 0.5})))
    case("unknown mode rejected", lambda: bad({"name": "Boat", "mode": "boat", "minutes_one_way": 5}))
    case("duplicate names rejected", lambda: bad(car, car))
    case("missing fuel economy rejected", lambda: bad({"name": "Car", "mode": "car", "minutes_one_way": 20, "fuel_price": 1.5}))
    case("negative price rejected", lambda: bad(dict(car, fuel_price=-1)))
    case("bad units rejected", lambda: bad(car, units="furlongs"))
    case("usable share above 1 rejected", lambda: bad(dict(tr, usable_time_share=1.5)))
    passed = 0
    for name, ok, err in cases:
        passed += ok
        print(("PASS " if ok else "FAIL ") + name + ("" if ok else f"  {err}"))
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Compare commute options per month and year, including time value")
    ap.add_argument("scenario", nargs="?")
    ap.add_argument("--value-of-time", type=float, help="override value_of_time_per_hour")
    ap.add_argument("--days-per-week", type=float, help="override days_per_week (e.g. 3 for hybrid work)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.scenario:
        ap.error("give a scenario JSON file, or --self-test")
    try:
        with open(a.scenario, encoding="utf-8") as fh:
            sc = json.load(fh)
        if a.days_per_week is not None and not 0.5 <= a.days_per_week <= 7:
            raise InputError("--days-per-week must be 0.5..7")
        res = evaluate(sc, a.value_of_time, a.days_per_week)
    except json.JSONDecodeError as e:
        print(f"error: scenario is not valid JSON: {e}", file=sys.stderr)
        return 2
    except (OSError, InputError, UnicodeDecodeError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(res, indent=2) if a.json else render(res), end="" if not a.json else "\n")
    return 0


if __name__ == "__main__":
    sys.exit(main())

---
name: houseplant-watering-schedule-planner
description: Builds a houseplant watering check calendar from a list of plants with pot size and material, light, drainage and last watering date. Adjusts each interval for pot, light, humidity and season (by hemisphere, stretching into winter), fits checks onto chosen weekdays, says what 'needs water' means and how much to give, and flags risks like pots with no drainage. Includes a stdlib Python planner with .ics export and --self-test.
---

# Houseplant Watering Schedule Planner

You help people keep houseplants alive without watering by the calendar alone. The plan tells them when to **check** each plant and what to look for; they water only when the plant's rule says so. You adapt to the real conditions (pot, light, heating, season), keep the routine simple (two fixed check days a week if they want), and point out the setups that cause most deaths: no drainage hole, succulents in dark corners, ferns drying out in terracotta.

## Files in this skill

- `scripts/watering_planner.py` - reads a plants CSV, assigns each plant a watering type, computes a check interval per season, builds the calendar (optionally snapped to weekdays), estimates water per plant, flags risky setups, and can export an .ics file (Python 3.8+ standard library only)
- `references/plant-water-profiles.md` - the six watering types, common plants in each, the "needs water" test and signs of over- and under-watering
- `references/adjustment-factors.md` - how pot size, pot material, light, humidity, season and drainage change the interval, with the multipliers the script uses and how to tune them after a few weeks
- `templates/watering-plan.md` - the one-page plan to hand back (weekly routine, per-plant cheat sheet, warnings, review date)
- `examples/plants.csv` - ten plants in a heated flat at the end of October
- `examples/plan-output.md` - the real output of the planner for that list

## Workflow

### 1. Collect the plant list
For each plant: a name, what it is (species or "looks like a succulent"), pot diameter in cm, pot material (plastic, glazed, terracotta, fabric, self-watering), light where it stands (low = far from a window, medium, bright = bright indirect, direct = sun on the leaves for hours), whether the pot has a drainage hole, and when it was last watered. Also ask the hemisphere, whether the heating is on (dry air), and which days suit a quick check. If the plant is unknown, ask for a photo description or treat it as "top_dry" and say so.

### 2. Run the planner
```
python3 scripts/watering_planner.py examples/plants.csv --start 2026-10-30 --weeks 6 --check-days Mon,Thu --humidity low
python3 scripts/watering_planner.py plants.csv --hemisphere south --weeks 8 --ics plants.ics
python3 scripts/watering_planner.py plants.csv --json
python3 scripts/watering_planner.py --self-test
```
Exit 0 = plan written, 1 = plan written but a HIGH warning needs action (e.g. no drainage), 2 = bad input (unknown material or light, pot size in mm, bad date). Without code, use the type table and multipliers in the references by hand.

### 3. Check the result before handing it over
- Each plant has a check interval now and, if the plan crosses a season, the new interval (e.g. "7 d (winter: 9 d)").
- Plants that want to stay moist (ferns, calathea, peace lily, basil) may need more check days than the routine allows; the planner says so. Suggest a third check day, a plastic pot, or self-watering only for these.
- "Overdue" means the last watering plus the interval is already past: check that plant first.
- Read the warnings and turn HIGH ones into the first action of the plan.

### 4. Deliver
Fill `templates/watering-plan.md`: the weekly routine (which plants on which day), a per-plant cheat sheet with the "water when" test and amount, warnings with what to do, and a review date in 2-3 weeks to lengthen or shorten intervals based on what they found at each check.

## Example result
Ten plants, start Friday 2026-10-30, six weeks, checks on Mondays and Thursdays, heating on (low humidity). Ferns, calathea, the peace lily and basil are checked every check day; monstera about weekly (Thursdays); pothos weekly (Mondays); the snake plant every 16 days, stretching to 21 in December; the ZZ plant every 20 days; the cactus every 6 days now, 9 in winter (it is overdue, last watered 15 October). The peace lily sits in a decorative pot with no hole (HIGH: use a nursery pot inside it and empty the cover pot after watering). The fern in terracotta and the basil would like checks every 1-2 days, which twice a week cannot cover. See `examples/plan-output.md`.

## Rules

- Never prescribe watering on a fixed schedule without a check; always pair each check with the plant's "water when" test.
- Water thoroughly until it drains, then empty the saucer after 15 minutes; never leave a pot standing in water (orchids: soak, then drain fully).
- In winter and in low light, plants use less water: lengthen intervals rather than giving smaller sips.
- Treat yellowing plus wet soil as overwatering, not thirst; say so before suggesting more water.
- Do not guess a species from a vague name; ask or state the type you assumed.
- Mention pets if a plant is toxic only when the user asks about safety or mentions pets/children; do not pad the plan.
FILE:references/plant-water-profiles.md
# Watering types

| Type | Typical plants | Water when | Base check interval* | Winter slow-down |
|---|---|---|---|---|
| succulent | cactus, aloe, echeveria, jade, haworthia, string of pearls | soil dry all the way down: a wooden chopstick pushed to the bottom comes out clean and dry; pot feels light | 10 days | x2.5 (many cacti need almost no water Dec-Feb) |
| dry_tolerant | snake plant (sansevieria), ZZ plant, ponytail palm, yucca, hoya, peperomia | at least 3/4 of the soil dry | 12 days | x2.0 |
| top_dry | pothos, monstera, philodendron, rubber plant, fiddle leaf fig, dracaena, spider plant, money tree, aglaonema, alocasia, anthurium, parlor palm, begonia, Christmas cactus | top third dry (finger test to the second knuckle in a 15 cm pot) | 6 days | x1.6 |
| evenly_moist | Boston and maidenhair fern, calathea, maranta (prayer plant), peace lily, fittonia | top 1-2 cm just dry; never fully dry | 3 days | x1.3 |
| orchid | phalaenopsis in bark | roots silvery-grey (green = still wet) and bark dry; soak 10 min, drain fully | 7 days | x1.4 |
| herb | basil, mint, parsley on a windowsill | top 1-2 cm dry | 2 days | x1.2 |

*Base = spring, 15 cm plastic pot with drainage, medium light, normal humidity. Autumn is halfway between spring and winter; summer is x0.85. See `adjustment-factors.md`.

## How to check (30 seconds per plant)
1. **Finger test:** push a finger into the soil to the depth in the rule. Dry and crumbly = dry; cool and sticking = moist.
2. **Weight:** lift small pots right after watering once, so you know "full" vs "empty".
3. **Chopstick:** for deep pots and succulents, leave a wooden skewer in for a minute; dark and damp means wait.
4. **Moisture meters** are rough guides; they read salts as well as water and are often wrong in bark or very sandy mixes.

## Signs
| Overwatering (more common) | Underwatering |
|---|---|
| yellow lower leaves with soil still wet, soft or black stem base, mushy roots, fungus gnats, sour smell | crisp brown edges, drooping that recovers within hours of watering, soil pulling away from the pot edge, very light pot |
| Fix: stop watering, check roots, repot in dry mix if rotten, lengthen the interval | Fix: soak thoroughly (bottom-water 20-30 min for hydrophobic soil), shorten the interval a little |

Drooping with **wet** soil means roots are damaged: do not add water.

## Watering technique
- Water slowly over the whole surface until water runs out of the hole; wait, then empty the saucer after about 15 minutes.
- Room-temperature water. Calathea and some ferns brown at the tips with hard or softened water; rain or filtered water helps.
- Bottom-watering (stand the pot in water for 20-30 min) works for small pots and dry, shrinking soil; top-water now and then to flush salts.
- Self-watering pots: top up the reservoir when empty and let it stay empty for a day or two now and then so roots get air; not for succulents.
FILE:references/adjustment-factors.md
# Adjustment factors

Check interval = base days (type) x pot size x pot material x light x humidity x season, rounded, limited to 1..45 days. These are the multipliers in `scripts/watering_planner.py`.

| Factor | Value | Multiplier | Why |
|---|---|---|---|
| Pot diameter | under 10 cm | 0.6 | little soil, dries in days |
| | 10-13 cm | 0.8 | |
| | 14-19 cm | 1.0 | reference |
| | 20-27 cm | 1.3 | more soil holds water longer |
| | 28 cm and up | 1.6 | big pots stay wet at the bottom long after the top is dry: check deep |
| Material | plastic, glazed, ceramic, metal | 1.0 | walls do not breathe |
| | terracotta / unglazed clay | 0.75 | walls wick and evaporate water |
| | fabric grow bag | 0.7 | dries from all sides |
| | self-watering | 1.5 | reservoir feeds the soil; check the reservoir instead |
| Light | low (2+ m from a window, north room) | 1.4 | little growth, little use |
| | medium | 1.0 | |
| | bright indirect | 0.85 | |
| | direct sun on the leaves | 0.7 | |
| Humidity | low (heating on, below ~35 %) | 0.85 | soil and leaves lose water faster |
| | normal | 1.0 | |
| | high (bathroom, humidifier) | 1.15 | |
| Season | spring | 1.0 | |
| | summer | 0.85 | |
| | autumn | halfway to winter | growth slows as days shorten |
| | winter | type's winter slow-down (x1.2 to x2.5) | |

Seasons: northern hemisphere Dec-Feb winter, Mar-May spring, Jun-Aug summer, Sep-Nov autumn; southern hemisphere shifted by six months. Next to a radiator or in a heated conservatory, use humidity "low" even in winter.

## Drainage
No hole is the single biggest cause of root rot. Best: keep the plant in its plastic nursery pot inside the decorative pot and empty the outer pot 15 minutes after watering. If it must stay in a pot without a hole, give about half the usual amount and tip the pot to check for standing water. The planner flags this as HIGH.

## Amount
About 15-25 % of the pot volume, until water drains out of the hole. The planner estimates pot volume from the diameter (straight-sided pot about 0.9x as tall as wide), so a 15 cm pot gets about 450 ml, a 24 cm pot about 1.75 l. Succulents and dry-tolerant plants get a thorough soak too, just less often.

## Tune after two or three weeks
- Soil still moist at most checks: lengthen that plant's interval by 25-50 % (or move it to "low" light if it is far from the window).
- Soil bone-dry at every check and the plant droops: shorten by 25 %.
- Write the changes into the CSV (e.g. switch the type or light) and re-run, rather than remembering exceptions.
- Re-run the plan when the heating goes on or off, when you repot (bigger pot = longer interval), or when you move a plant.

## Not covered by the interval
- Newly repotted plants: water once thoroughly, then wait until the rule says so.
- Dormant bulbs and cacti in a cold winter rest (5-12 C): almost no water; a monthly check is enough.
- Fertilizing: only in spring and summer, at half strength, on a watering day.
FILE:templates/watering-plan.md
# Plant care plan: <home / room>

**Period:** <2026-10-30 to 2026-12-10>   **Check days:** <Mon and Thu, 5-10 minutes>
**Conditions:** <northern hemisphere, heating on (dry air)>   **Review on:** <2026-11-16>

## Do first
- <Peace lily: no drainage hole - move it into a plastic nursery pot inside the cover pot; empty the cover pot 15 min after watering>
- <Spike (cactus): overdue - check on Monday>

## Weekly routine
| Day | Check these plants |
|---|---|
| <Mon> | <ferns, calathea, peace lily, basil, orchid, pothos, cactus (every 2nd Mon in December)> |
| <Thu> | <ferns, calathea, peace lily, basil, orchid, monstera; snake plant every 2-3 weeks> |

## Cheat sheet
| Plant | Water when | About | Notes |
|---|---|---|---|
| <Monty (monstera)> | <top third dry> | <~1.75 l until it drains> | <bright east window> |
| <Sansa (snake plant)> | <3/4 dry> | <~450 ml> | <December: every 3 weeks> |

## How to check
- Finger in the soil to the depth in the "water when" column; water only if dry to that depth.
- Water until it drains, empty the saucer after 15 minutes.
- Wet soil + yellow leaves = too much water: skip and tell me.

## Warnings
- <Fernando (Boston fern) in terracotta dries in 2 days with the heating on: add a Saturday check or move it to a plastic pot>
- <Basil wants daily checks on the sunny sill; bottom-water when you pass by>

## At the review
For each plant, note whether the soil was usually still moist (lengthen) or bone dry (shorten) at checks; I will update the plan.
FILE:examples/plants.csv
name,plant,pot_cm,pot_material,light,drainage,last_watered,notes
Monty,monstera,24,plastic,bright,yes,2026-10-28,living room by the east window
Pothos shelf,pothos,14,glazed,medium,yes,2026-10-27,trailing from the bookshelf
Sansa,snake plant,17,terracotta,low,yes,2026-10-20,hallway corner
Zed,zz plant,20,plastic,medium,yes,,new from the shop
Fernando,boston fern,20,terracotta,bright,yes,2026-10-29,bathroom shelf
Cal,calathea,15,plastic,medium,yes,2026-10-28,bedroom
Spike,cactus,10,terracotta,direct,yes,2026-10-15,south windowsill
Peace lily,peace lily,18,glazed,low,no,2026-10-26,decorative pot with no hole
Orchid,phalaenopsis,12,plastic,bright,yes,2026-10-25,kitchen window
Basil,basil,13,terracotta,direct,yes,2026-10-29,kitchen windowsill
FILE:examples/plan-output.md
# Houseplant watering plan: 2026-10-30 to 2026-12-10

Hemisphere: north   Season at start: autumn   Humidity: low   Check days: Mon, Thu   Plants: 10

A check is not a watering: feel the soil and water only when the rule says so.

## Plants

| Plant | Type | Pot | Light | Check every | Water when | About | Checks |
|---|---|---|---|---|---|---|---|
| Monty (monstera) | top_dry | 24 cm plastic | bright | 7 d (winter: 9 d) | top third of the soil dry (about 3-5 cm in a 15 cm pot) | ~1750 ml (until it drains) | 6 |
| Pothos shelf (pothos) | top_dry | 14 cm glazed | medium | 7 d (winter: 8 d) | top third of the soil dry (about 3-5 cm in a 15 cm pot) | ~350 ml (until it drains) | 6 |
| Sansa (snake plant) | dry_tolerant | 17 cm terracotta | low | 16 d (winter: 21 d) | soil dry at least 3/4 of the way down | ~450 ml (until it drains) | 3 |
| Zed (zz plant) | dry_tolerant | 20 cm plastic | medium | 20 d | soil dry at least 3/4 of the way down | ~750 ml (until it drains) | 2 |
| Fernando (boston fern) | evenly_moist | 20 cm terracotta | bright | 2 d (winter: 3 d) | top 1-2 cm just dry; never let it dry out fully | ~1000 ml (until it drains) | 12 |
| Cal (calathea) | evenly_moist | 15 cm plastic | medium | 3 d (winter: 3 d) | top 1-2 cm just dry; never let it dry out fully | ~450 ml (until it drains) | 12 |
| Spike (cactus) (overdue: check first day) | succulent | 10 cm terracotta | direct | 6 d (winter: 9 d) | soil dry all the way down (chopstick comes out clean and dry) | ~100 ml (until it drains) | 6 |
| Peace lily (peace lily) | evenly_moist | 18 cm glazed, NO hole | low | 4 d (winter: 5 d) | top 1-2 cm just dry; never let it dry out fully | ~375 ml, no more | 12 |
| Orchid (phalaenopsis) | orchid | 12 cm plastic | bright | 5 d (winter: 6 d) | roots silvery-grey and bark dry; soak 10 min, drain fully | soak 10 min | 11 |
| Basil (basil) | herb | 13 cm terracotta | direct | 1 d (winter: 1 d) | top 1-2 cm dry | ~350 ml (until it drains) | 12 |

## Calendar

| Date | Day | Season | Check |
|---|---|---|---|
| 2026-11-02 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike, Zed |
| 2026-11-05 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-11-09 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-11-12 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
| 2026-11-16 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-11-19 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-11-23 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike, Zed |
| 2026-11-26 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
| 2026-11-30 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-12-03 | Thu | winter | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-12-07 | Mon | winter | Basil, Cal, Fernando, Peace lily, Pothos shelf, Spike |
| 2026-12-10 | Thu | winter | Basil, Cal, Fernando, Monty, Orchid, Peace lily |

## Warnings

| Sev | Plant | Note |
|---|---|---|
| HIGH | Peace lily | pot has no drainage hole: water pools at the bottom and roots rot. Repot, or keep the plant in a nursery pot inside the cover pot and empty the cover pot 15 min after watering |
| LOW | Fernando | terracotta pot dries this plant very fast; a plastic or glazed pot keeps it evenly moist |
| LOW | Fernando | check days push some checks more than a day late (e.g. due 2026-11-07, planned 2026-11-09); add a check day or feel the soil in between |
| LOW | Basil | check days push some checks more than a day late (e.g. due 2026-11-03, planned 2026-11-05); add a check day or feel the soil in between |

Intervals assume the plant is established in a free-draining mix. After 2-3 weeks, lengthen an interval if the soil is still moist at most checks, shorten it if it is always bone dry.
FILE:scripts/watering_planner.py
#!/usr/bin/env python3
"""Houseplant watering schedule planner (Python 3.8+ standard library only).

Reads a CSV of plants (species or watering type, pot diameter, pot material, light,
drainage, optional last watering date) and builds a check calendar: how often to
check each plant in the current season, what "needs water" means for it, roughly how
much to give, and which plants to check on which date. Intervals stretch
automatically as the plan crosses into autumn and winter (or shrink into summer), by
hemisphere. Checks can be snapped to fixed weekdays (e.g. Mon,Thu) so the plan fits a
routine. Optional .ics export for a calendar app.

A check is not a watering: on each check, feel the soil and water only if the plant's
rule says so. The intervals are starting points; adjust them after two or three weeks
of real checks (see references/adjustment-factors.md).

Usage:
  python3 watering_planner.py plants.csv [--start 2026-10-30] [--weeks 4]
        [--hemisphere north|south] [--humidity low|normal|high]
        [--check-days Mon,Thu] [--ics plan.ics] [--json]
  python3 watering_planner.py --self-test
plants.csv columns: name, plant (species or type), pot_cm, pot_material
(plastic|glazed|ceramic|terracotta|fabric|self-watering), light (low|medium|bright|direct),
drainage (yes|no), last_watered (YYYY-MM-DD, optional), notes (optional).
Types: succulent, dry_tolerant, top_dry, evenly_moist, orchid, herb.
Exit codes: 0 = plan written, 1 = plan written with HIGH warnings (e.g. no drainage), 2 = bad input.
"""
import argparse, csv, datetime as dt, io, json, math, sys

PROFILES = {
    #               base days (spring, 15 cm plastic, medium light), winter factor, rule, share of pot volume per watering
    "succulent":    (10, 2.5, "soil dry all the way down (chopstick comes out clean and dry)", 0.15),
    "dry_tolerant": (12, 2.0, "soil dry at least 3/4 of the way down", 0.15),
    "top_dry":      (6, 1.6, "top third of the soil dry (about 3-5 cm in a 15 cm pot)", 0.20),
    "evenly_moist": (3, 1.3, "top 1-2 cm just dry; never let it dry out fully", 0.20),
    "orchid":       (7, 1.4, "roots silvery-grey and bark dry; soak 10 min, drain fully", 0.0),
    "herb":         (2, 1.2, "top 1-2 cm dry", 0.25),
}
SPECIES = {
    "cactus": "succulent", "aloe": "succulent", "aloe vera": "succulent", "echeveria": "succulent",
    "jade": "succulent", "jade plant": "succulent", "haworthia": "succulent", "string of pearls": "succulent",
    "christmas cactus": "top_dry", "snake plant": "dry_tolerant", "sansevieria": "dry_tolerant",
    "zz plant": "dry_tolerant", "zamioculcas": "dry_tolerant", "ponytail palm": "dry_tolerant",
    "hoya": "dry_tolerant", "pothos": "top_dry", "monstera": "top_dry", "philodendron": "top_dry",
    "rubber plant": "top_dry", "ficus elastica": "top_dry", "fiddle leaf fig": "top_dry",
    "dracaena": "top_dry", "spider plant": "top_dry", "money tree": "top_dry", "pachira": "top_dry",
    "chinese evergreen": "top_dry", "aglaonema": "top_dry", "dieffenbachia": "top_dry",
    "yucca": "dry_tolerant", "bird of paradise": "top_dry", "alocasia": "top_dry", "anthurium": "top_dry",
    "parlor palm": "top_dry", "peperomia": "dry_tolerant", "begonia": "top_dry",
    "fern": "evenly_moist", "boston fern": "evenly_moist", "maidenhair fern": "evenly_moist",
    "calathea": "evenly_moist", "prayer plant": "evenly_moist", "maranta": "evenly_moist",
    "peace lily": "evenly_moist", "spathiphyllum": "evenly_moist", "fittonia": "evenly_moist",
    "orchid": "orchid", "phalaenopsis": "orchid", "basil": "herb", "mint": "herb", "parsley": "herb",
}
MATERIAL = {"plastic": 1.0, "glazed": 1.0, "ceramic": 1.0, "metal": 1.0, "terracotta": 0.75,
            "clay": 0.75, "unglazed": 0.75, "fabric": 0.7, "self-watering": 1.5}
LIGHT = {"low": 1.4, "medium": 1.0, "bright": 0.85, "direct": 0.7}
HUMIDITY = {"low": 0.85, "normal": 1.0, "high": 1.15}
SEASON_FACTOR = {"spring": 1.0, "summer": 0.85}
DAY_NAMES = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]


class InputError(Exception):
    pass


def season_of(d, hemisphere):
    m = d.month if hemisphere == "north" else (d.month + 5) % 12 + 1
    return {12: "winter", 1: "winter", 2: "winter", 3: "spring", 4: "spring", 5: "spring",
            6: "summer", 7: "summer", 8: "summer"}.get(m, "autumn")


def pot_factor(cm):
    if cm < 10:
        return 0.6
    if cm < 14:
        return 0.8
    if cm < 20:
        return 1.0
    if cm < 28:
        return 1.3
    return 1.6


def pot_litres(cm):
    # straight-sided pot about 0.9x as tall as wide, minus ~10 % for the rim gap
    r = cm / 2.0
    return math.pi * r * r * (0.9 * cm) * 0.9 / 1000.0


def interval_days(p, season, humidity):
    base, winter, _, _ = PROFILES[p["type"]]
    # autumn sits halfway between spring and the plant's winter slow-down
    sf = {"winter": winter, "autumn": (1 + winter) / 2}.get(season) or SEASON_FACTOR[season]
    days = base * pot_factor(p["pot_cm"]) * MATERIAL[p["material"]] * LIGHT[p["light"]] * HUMIDITY[humidity] * sf
    return max(1, min(45, int(round(days))))


def parse_date(s, what):
    try:
        return dt.date.fromisoformat(s.strip())
    except ValueError:
        raise InputError(f"bad date '{s}' for {what} (use YYYY-MM-DD)")


def load_plants(text):
    rows = list(csv.DictReader(io.StringIO(text)))
    if not rows:
        raise InputError("plants CSV has no rows")
    cols = {c.strip().lower(): c for c in rows[0] if c}
    if "name" not in cols:
        raise InputError("plants CSV needs at least a 'name' column (plus plant, pot_cm, pot_material, light, drainage)")
    plants, warnings = [], []
    for i, r in enumerate(rows, 2):
        g = lambda k, d="": ((r.get(cols[k]) or "").strip() if k in cols else "") or d
        name = g("name")
        if not name:
            raise InputError(f"row {i}: empty name")
        kind = g("plant", g("type", "")).lower()
        if kind in PROFILES:
            ptype = kind
        elif kind in SPECIES:
            ptype = SPECIES[kind]
        else:
            ptype = next((v for k, v in SPECIES.items() if k in kind), None) if kind else None
            if ptype is None:
                ptype = "top_dry"
                warnings.append(("MEDIUM", name, f"unknown plant '{kind or '?'}': using type top_dry; set the plant column to one of {', '.join(PROFILES)}"))
        try:
            pot = float(g("pot_cm", "0") or 0)
        except ValueError:
            raise InputError(f"row {i} ({name}): pot_cm must be a number of centimetres")
        if pot <= 0:
            pot = 15.0
            warnings.append(("LOW", name, "no pot size given: assumed 15 cm"))
        if pot > 80:
            raise InputError(f"row {i} ({name}): pot_cm {pot} looks wrong (centimetres, not millimetres?)")
        mat = g("pot_material", "plastic").lower()
        if mat not in MATERIAL:
            raise InputError(f"row {i} ({name}): pot_material '{mat}' (use {', '.join(MATERIAL)})")
        light = g("light", "medium").lower().replace("bright indirect", "bright").replace("full sun", "direct")
        if light not in LIGHT:
            raise InputError(f"row {i} ({name}): light '{light}' (use low, medium, bright, direct)")
        drainage = g("drainage", "yes").lower() not in ("no", "n", "false", "0")
        last = parse_date(g("last_watered"), f"{name} last_watered") if g("last_watered") else None
        p = {"name": name, "plant": kind or ptype, "type": ptype, "pot_cm": pot, "material": mat,
             "light": light, "drainage": drainage, "last_watered": last, "notes": g("notes")}
        plants.append(p)
        if not drainage:
            warnings.append(("HIGH", name, "pot has no drainage hole: water pools at the bottom and roots rot. Repot, or keep the plant in a nursery pot inside the cover pot and empty the cover pot 15 min after watering"))
        if ptype == "succulent" and light == "low":
            warnings.append(("MEDIUM", name, "succulent in low light: it will stretch and rot easily; move it to the brightest window and water even less"))
        if ptype == "evenly_moist" and light == "direct":
            warnings.append(("MEDIUM", name, "moisture-loving plant in direct sun: leaves scorch and soil dries within a day; move it out of direct sun"))
        if ptype == "evenly_moist" and mat in ("terracotta", "clay", "unglazed", "fabric"):
            warnings.append(("LOW", name, f"{mat} pot dries this plant very fast; a plastic or glazed pot keeps it evenly moist"))
        if ptype == "orchid" and mat not in ("plastic",):
            warnings.append(("LOW", name, "orchids are easiest in a clear plastic pot with drainage, so you can see the roots"))
        if mat == "self-watering" and ptype in ("succulent", "dry_tolerant", "orchid"):
            warnings.append(("MEDIUM", name, "self-watering pots keep the soil wet; not suited to plants that need to dry out"))
    return plants, warnings


def amount_text(p):
    _, _, _, share = PROFILES[p["type"]]
    if p["type"] == "orchid":
        return "soak 10 min"
    if p["material"] == "self-watering":
        return "refill reservoir"
    ml = pot_litres(p["pot_cm"]) * 1000 * share
    ml = int(round(ml / 50.0) * 50) or 50
    return f"~{ml} ml (until it drains)" if p["drainage"] else f"~{ml // 2} ml, no more"


def snap(due, prev, allowed):
    """Allowed weekday nearest to the due date (ties go earlier), always after prev."""
    if not allowed:
        return due
    best = None
    for off in (0, -1, 1, -2, 2, -3, 3):
        d = due + dt.timedelta(days=off)
        if d > prev and d.weekday() in allowed:
            best = d
            break
    if best is None:
        best = max(due, prev + dt.timedelta(days=1))
        while best.weekday() not in allowed:
            best += dt.timedelta(days=1)
    return best


def plan(plants, start, weeks, hemisphere="north", humidity="normal", check_days=None):
    end = start + dt.timedelta(days=7 * weeks - 1)
    allowed = {DAY_NAMES.index(x) for x in check_days} if check_days else set()
    cal, per_plant, notes = {}, [], []
    for p in plants:
        s0 = season_of(start, hemisphere)
        iv = interval_days(p, s0, humidity)
        if p["last_watered"]:
            due = p["last_watered"] + dt.timedelta(days=iv)
            overdue = due < start
            first = max(due, start)
        else:
            overdue, first = False, start
        d = snap(first, start - dt.timedelta(days=1), allowed) if allowed else first
        dates, prev = [], None
        while d <= end:
            dates.append(d)
            cal.setdefault(d, []).append(p["name"])
            step = interval_days(p, season_of(d, hemisphere), humidity)
            due = d + dt.timedelta(days=step)
            nd = snap(due, d, allowed)
            if allowed and (nd - due).days > max(1, step // 5):
                notes.append((p["name"], due, nd))
            prev, d = d, nd
        later = {season_of(x, hemisphere) for x in dates} - {s0}
        per_plant.append({**p, "interval_now": iv, "season_now": s0,
                          "intervals_later": {s: interval_days(p, s, humidity) for s in sorted(later)},
                          "rule": PROFILES[p["type"]][2], "amount": amount_text(p),
                          "checks": [x.isoformat() for x in dates], "overdue": overdue})
    return {"start": start, "end": end, "hemisphere": hemisphere, "humidity": humidity,
            "check_days": check_days or [], "plants": per_plant,
            "calendar": [(d, sorted(cal[d], key=str.lower)) for d in sorted(cal)], "late_snaps": notes}


def render(res, warnings):
    st, en = res["start"], res["end"]
    out = [f"# Houseplant watering plan: {st.isoformat()} to {en.isoformat()}", "",
           f"Hemisphere: {res['hemisphere']}   Season at start: {season_of(st, res['hemisphere'])}   "
           f"Humidity: {res['humidity']}   Check days: {', '.join(res['check_days']) or 'any day'}   Plants: {len(res['plants'])}", "",
           "A check is not a watering: feel the soil and water only when the rule says so.", "",
           "## Plants", "",
           "| Plant | Type | Pot | Light | Check every | Water when | About | Checks |",
           "|---|---|---|---|---|---|---|---|"]
    for p in res["plants"]:
        iv = f"{p['interval_now']} d"
        if p["intervals_later"]:
            iv += " (" + ", ".join(f"{s}: {v} d" for s, v in p["intervals_later"].items()) + ")"
        pot = f"{p['pot_cm']:g} cm {p['material']}" + ("" if p["drainage"] else ", NO hole")
        flag = " (overdue: check first day)" if p["overdue"] else ""
        out.append(f"| {p['name']} ({p['plant']}){flag} | {p['type']} | {pot} | {p['light']} | {iv} | {p['rule']} | {p['amount']} | {len(p['checks'])} |")
    out += ["", "## Calendar", "", "| Date | Day | Season | Check |", "|---|---|---|---|"]
    for d, names in res["calendar"]:
        out.append(f"| {d.isoformat()} | {DAY_NAMES[d.weekday()]} | {season_of(d, res['hemisphere'])} | {', '.join(names)} |")
    if warnings or res["late_snaps"]:
        out += ["", "## Warnings", "", "| Sev | Plant | Note |", "|---|---|---|"]
        order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
        for sev, name, msg in sorted(warnings, key=lambda w: (order[w[0]], w[1].lower())):
            out.append(f"| {sev} | {name} | {msg} |")
        seen = set()
        for name, due, nd in res["late_snaps"]:
            if name in seen:
                continue
            seen.add(name)
            out.append(f"| LOW | {name} | check days push some checks more than a day late (e.g. due {due.isoformat()}, planned {nd.isoformat()}); add a check day or feel the soil in between |")
    out += ["", "Intervals assume the plant is established in a free-draining mix. After 2-3 weeks, lengthen an interval if the soil is still moist at most checks, shorten it if it is always bone dry."]
    return "\n".join(out) + "\n"


def to_ics(res, stamp):
    lines = ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//houseplant-watering-schedule-planner//EN", "CALSCALE:GREGORIAN"]
    for d, names in res["calendar"]:
        nd = d + dt.timedelta(days=1)
        lines += ["BEGIN:VEVENT", f"UID:plants-{d.strftime('%Y%m%d')}@watering-planner", f"DTSTAMP:{stamp}",
                  f"DTSTART;VALUE=DATE:{d.strftime('%Y%m%d')}", f"DTEND;VALUE=DATE:{nd.strftime('%Y%m%d')}",
                  "SUMMARY:" + ics_escape("Check plants: " + ", ".join(names)), "TRANSP:TRANSPARENT", "END:VEVENT"]
    lines.append("END:VCALENDAR")
    return "\r\n".join(fold(l) for l in lines) + "\r\n"


def ics_escape(s):
    return s.replace("\\", "\\\\").replace(";", "\\;").replace(",", "\\,").replace("\n", "\\n")


def fold(line):
    b = line.encode("utf-8")
    if len(b) <= 75:
        return line
    parts, cur = [], b""
    for ch in line:
        e = ch.encode("utf-8")
        if len(cur) + len(e) > (75 if not parts else 74):
            parts.append(cur.decode("utf-8")); cur = b""
        cur += e
    parts.append(cur.decode("utf-8"))
    return "\r\n ".join(parts)


def self_test():
    H = "name,plant,pot_cm,pot_material,light,drainage,last_watered\n"
    def run(rows, **kw):
        plants, warns = load_plants(H + rows)
        return plan(plants, kw.pop("start", dt.date(2026, 4, 6)), kw.pop("weeks", 4), **kw), warns
    cases = []
    def case(name, fn):
        try:
            ok = bool(fn())
            err = ""
        except Exception as e:  # noqa
            ok, err = False, repr(e)
        cases.append((name, ok, err))

    case("succulent checked less often than fern", lambda: run("A,cactus,15,plastic,medium,yes,\nB,fern,15,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] > run("A,cactus,15,plastic,medium,yes,\nB,fern,15,plastic,medium,yes,\n")[0]["plants"][1]["interval_now"])
    case("base interval top_dry 15 cm plastic medium spring = 6", lambda: run("A,pothos,15,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] == 6)
    case("small pot dries faster", lambda: run("A,pothos,9,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] < 6)
    case("big pot lasts longer", lambda: run("A,pothos,30,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"] > 6)
    case("terracotta dries faster than plastic", lambda: run("A,pothos,15,terracotta,medium,yes,\n")[0]["plants"][0]["interval_now"] < 6)
    case("low light lengthens, direct sun shortens", lambda: run("A,pothos,15,plastic,low,yes,\n")[0]["plants"][0]["interval_now"] > 6 > run("A,pothos,15,plastic,direct,yes,\n")[0]["plants"][0]["interval_now"])
    case("winter stretches succulent 2.5x", lambda: run("A,cactus,15,plastic,medium,yes,\n", start=dt.date(2026, 1, 5))[0]["plants"][0]["interval_now"] == 25)
    case("summer shortens", lambda: run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 7, 6))[0]["plants"][0]["interval_now"] == 5)
    case("southern hemisphere: July is winter", lambda: season_of(dt.date(2026, 7, 1), "south") == "winter" and season_of(dt.date(2026, 1, 1), "south") == "summer")
    case("season boundaries north", lambda: [season_of(dt.date(2026, m, 15), "north") for m in (2, 3, 5, 6, 8, 9, 11, 12)] == ["winter", "spring", "spring", "summer", "summer", "autumn", "autumn", "winter"])
    case("interval grows across autumn->winter in plan", lambda: (lambda r: r["plants"][0]["intervals_later"].get("winter", 0) > r["plants"][0]["interval_now"])(run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 11, 16), weeks=4)[0]))
    case("checks spaced by interval", lambda: run("A,pothos,15,plastic,medium,yes,\n")[0]["plants"][0]["checks"][:3] == ["2026-04-06", "2026-04-12", "2026-04-18"])
    case("last_watered sets first check", lambda: run("A,pothos,15,plastic,medium,yes,2026-04-04\n")[0]["plants"][0]["checks"][0] == "2026-04-10")
    case("overdue goes to start", lambda: (lambda p: p["overdue"] and p["checks"][0] == "2026-04-06")(run("A,pothos,15,plastic,medium,yes,2026-03-20\n")[0]["plants"][0]))
    case("snap to check days (Mon,Thu)", lambda: all(dt.date.fromisoformat(x).weekday() in (0, 3) for x in run("A,pothos,15,plastic,medium,yes,\nB,cactus,12,terracotta,bright,yes,\n", check_days=["Mon", "Thu"])[0]["calendar"] and [x for p in run("A,pothos,15,plastic,medium,yes,\nB,cactus,12,terracotta,bright,yes,\n", check_days=["Mon", "Thu"])[0]["plants"] for x in p["checks"]]))
    case("snap to nearest check day (Sun -> Mon)", lambda: snap(dt.date(2026, 4, 12), dt.date(2026, 4, 6), {0, 3}) == dt.date(2026, 4, 13))
    case("snap tie goes earlier (Tue between Mon and Thu? no: Tue -> Mon)", lambda: snap(dt.date(2026, 4, 14), dt.date(2026, 4, 9), {0, 3}) == dt.date(2026, 4, 13))
    case("snap never on or before the previous check", lambda: snap(dt.date(2026, 4, 7), dt.date(2026, 4, 6), {0, 3}) == dt.date(2026, 4, 9))
    case("autumn between spring and winter", lambda: 6 < run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 10, 5))[0]["plants"][0]["interval_now"] < run("A,pothos,15,plastic,medium,yes,\n", start=dt.date(2026, 12, 7))[0]["plants"][0]["interval_now"])
    case("late snap noted for fast plant", lambda: len(run("A,basil,9,terracotta,direct,yes,\n", check_days=["Mon"])[0]["late_snaps"]) > 0)
    case("no drainage -> HIGH warning and half amount", lambda: (lambda r: any(w[0] == "HIGH" for w in r[1]) and "no more" in r[0]["plants"][0]["amount"])(run("A,pothos,15,glazed,medium,no,\n")))
    case("unknown plant -> top_dry with warning", lambda: (lambda r: r[0]["plants"][0]["type"] == "top_dry" and any("unknown plant" in w[2] for w in r[1]))(run("A,triffid,15,plastic,medium,yes,\n")))
    case("species substring match", lambda: run("A,variegated monstera,15,plastic,medium,yes,\n")[0]["plants"][0]["type"] == "top_dry")
    case("succulent low light warning", lambda: any("stretch" in w[2] for w in run("A,echeveria,10,terracotta,low,yes,\n")[1]))
    case("fern in direct sun warning", lambda: any("scorch" in w[2] for w in run("A,boston fern,20,plastic,direct,yes,\n")[1]))
    case("self-watering succulent warning", lambda: any("self-watering" in w[2] for w in run("A,cactus,15,self-watering,bright,yes,\n")[1]))
    case("orchid amount is soak", lambda: run("A,orchid,12,plastic,bright,yes,\n")[0]["plants"][0]["amount"] == "soak 10 min")
    case("amount scales with pot", lambda: int(run("A,pothos,25,plastic,medium,yes,\n")[0]["plants"][0]["amount"][1:].split()[0]) > int(run("A,pothos,12,plastic,medium,yes,\n")[0]["plants"][0]["amount"][1:].split()[0]))
    case("low humidity shortens", lambda: run("A,fern,20,plastic,medium,yes,\n", humidity="low")[0]["plants"][0]["interval_now"] <= run("A,fern,20,plastic,medium,yes,\n")[0]["plants"][0]["interval_now"])
    case("interval never below 1 day", lambda: run("A,basil,6,fabric,direct,yes,\n", start=dt.date(2026, 7, 6), humidity="low")[0]["plants"][0]["interval_now"] >= 1)
    case("missing pot size assumed 15", lambda: (lambda r: r[0]["plants"][0]["pot_cm"] == 15 and any("assumed 15" in w[2] for w in r[1]))(run("A,pothos,,plastic,medium,yes,\n")))
    def bad(rows):
        try:
            load_plants(H + rows); return False
        except InputError:
            return True
    case("bad material rejected", lambda: bad("A,pothos,15,wood,medium,yes,\n"))
    case("bad light rejected", lambda: bad("A,pothos,15,plastic,dim,yes,\n"))
    case("pot in mm rejected", lambda: bad("A,pothos,150,plastic,medium,yes,\n"))
    case("bad date rejected", lambda: bad("A,pothos,15,plastic,medium,yes,30/10/2026\n"))
    case("ics has one event per date, CRLF, escaped commas", lambda: (lambda r, t: t.count("BEGIN:VEVENT") == len(r["calendar"]) and "\r\n" in t and "\\," in t)(*(lambda r: (r, to_ics(r, "20261030T000000Z")))(run("A,pothos,15,plastic,medium,yes,\nB,fern,15,plastic,medium,yes,\n")[0])))
    case("ics lines folded to 75 octets", lambda: all(len(l.encode()) <= 75 for l in to_ics(run("".join(f"Plant number {i},pothos,15,plastic,medium,yes,\n" for i in range(8)))[0], "20261030T000000Z").split("\r\n")))
    passed = 0
    for name, ok, err in cases:
        passed += ok
        print(("PASS " if ok else "FAIL ") + name + ("" if ok else f"  {err}"))
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Build a houseplant watering check calendar")
    ap.add_argument("plants", nargs="?")
    ap.add_argument("--start", help="first day of the plan, YYYY-MM-DD (default today)")
    ap.add_argument("--weeks", type=int, default=4)
    ap.add_argument("--hemisphere", choices=["north", "south"], default="north")
    ap.add_argument("--humidity", choices=list(HUMIDITY), default="normal", help="low = heating on / below ~35 %%")
    ap.add_argument("--check-days", help="snap checks to these weekdays, e.g. Mon,Thu")
    ap.add_argument("--ics", help="also write an .ics calendar file")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.plants:
        ap.error("give a plants CSV, or --self-test")
    try:
        start = parse_date(a.start, "--start") if a.start else dt.date.today()
        if not 1 <= a.weeks <= 26:
            raise InputError("--weeks must be 1..26")
        days = None
        if a.check_days:
            days = [x.strip()[:3].title() for x in a.check_days.split(",") if x.strip()]
            for x in days:
                if x not in DAY_NAMES:
                    raise InputError(f"unknown weekday '{x}' in --check-days")
        with open(a.plants, encoding="utf-8") as fh:
            plants, warnings = load_plants(fh.read())
    except (OSError, InputError, UnicodeDecodeError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    res = plan(plants, start, a.weeks, a.hemisphere, a.humidity, days)
    if a.ics:
        stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
        with open(a.ics, "w", encoding="utf-8", newline="") as fh:
            fh.write(to_ics(res, stamp))
    if a.json:
        out = {**res, "start": res["start"].isoformat(), "end": res["end"].isoformat(),
               "calendar": [{"date": d.isoformat(), "plants": n} for d, n in res["calendar"]],
               "late_snaps": [{"plant": n, "due": d.isoformat(), "planned": p.isoformat()} for n, d, p in res["late_snaps"]],
               "plants": [{**p, "last_watered": p["last_watered"].isoformat() if p["last_watered"] else None} for p in res["plants"]],
               "warnings": [{"severity": s, "plant": n, "note": m} for s, n, m in warnings]}
        print(json.dumps(out, indent=2))
    else:
        sys.stdout.write(render(res, warnings))
    return 1 if any(w[0] == "HIGH" for w in warnings) else 0


if __name__ == "__main__":
    sys.exit(main())

---
name: dns-zone-record-linter
description: Lints a DNS zone file or a provider's CSV record export before it breaks web or mail - CNAME at the apex or next to other records, MX/NS pointing at a CNAME or IP, missing trailing dots, missing or duplicate SPF, +all/?all and the 10-lookup limit, DMARC and DKIM presence, syntax and key size, TTL extremes, private IPs and SOA mistakes. Returns corrected records. Includes an offline stdlib Python linter with --self-test.
---

# DNS Zone Record Linter

You review DNS records the way a careful DNS operator would before a migration or a mail setup goes live. You find the mistakes that silently break things (a CNAME at the apex, an MX that points at a CNAME, `mail.example.com` written without its trailing dot, two SPF records), explain the effect in plain words, and hand back corrected records. You work offline from the file; you never claim a live lookup you did not make.

## Files in this skill

- `scripts/dns_lint.py` - parses a BIND zone file ($ORIGIN, $TTL, @, relative names, multi-line SOA, quoted TXT) or a CSV export (name,type,value,ttl,priority) and reports findings with line numbers, then lists out-of-zone targets to check live (Python 3.8+ standard library only)
- `references/record-rules.md` - the rules behind each check with RFC pointers: CNAME exclusivity, MX/NS targets, trailing dots, SPF, DMARC, DKIM, TTL and SOA values
- `references/finding-codes.md` - every finding code with severity, when it is acceptable, and the usual fix
- `templates/dns-review.md` - the review to hand back (summary, fixes as records, live checks, rollout notes)
- `examples/example.com.zone` - a zone exported before a DNS host move, with mistakes on purpose
- `examples/example.com.fixed.zone` - the corrected zone (lints clean)
- `examples/lint-report.md` - the real output of the linter on the broken example

## Workflow

### 1. Get the records and the context
Ask for the zone file (BIND format, `dig AXFR` output or the provider's export) or a CSV (`name,type,value,ttl,priority`), the zone name, and what the domain is for: website only, sending mail (which services: Google Workspace, Microsoft 365, a newsletter tool, a helpdesk), or no mail at all. If the user pastes records from a provider UI, note that host names there usually have no trailing dot and that NS/SOA are often managed by the provider.

### 2. Run the linter
```
python3 scripts/dns_lint.py examples/example.com.zone
python3 scripts/dns_lint.py records.csv --origin example.com
python3 scripts/dns_lint.py zone.db --origin example.com --min-severity MEDIUM --ignore CAA_MISSING --json
python3 scripts/dns_lint.py --self-test
```
Exit 0 = no HIGH findings, 1 = HIGH findings, 2 = bad input (unclosed parenthesis or quote, unknown zone name). If you cannot run code, apply `references/record-rules.md` by hand in the same order.

### 3. Read the findings
- **HIGH** breaks resolution or mail now (CNAME conflicts, MX to CNAME, missing trailing dot, two SPF records, `+all`, DMARC at the wrong name, invalid SPF terms, weak DKIM key).
- **MEDIUM** is wrong or risky but may still work (missing DMARC/DKIM/SPF, `?all`, private IPs, TTL extremes, dangling targets, a single name server).
- **LOW** is hygiene (duplicates, `p=none`, 1024-bit DKIM, no CAA, obsolete SPF type).
- The linter counts only top-level SPF lookups; nested includes add more. It cannot see records that live at the provider (DKIM selectors created by a mail host) or targets outside the zone. Say so, and list the live checks from the "Out-of-zone targets" table (`dig +short CNAME shop.example.com`, `dig TXT _dmarc.example.com`).

### 4. Deliver
Fill `templates/dns-review.md`: a short summary, the corrected records in the user's format (zone lines or provider form fields), what to verify live, and the rollout order: lower TTLs a day ahead, change, verify, raise TTLs again; bump the SOA serial. For mail changes, recommend DMARC `p=none` with `rua` first, then `quarantine`, then `reject` once reports are clean.

## Example result
On `examples/example.com.zone` the linter reports 19 findings (HIGH 7, MEDIUM 8, LOW 4): the website was moved with `@ CNAME bakery-site.example.net.` (CNAME at the apex, next to SOA, NS, MX and TXT), `www` has both a CNAME and a verification TXT, `MX 10 mail.example.com` lacks its trailing dot so it means `mail.example.com.example.com.`, the backup MX points at a CNAME, there are two `v=spf1` records (one with `?all`), DMARC sits at `dmarc` instead of `_dmarc`, an old DKIM selector is revoked, the SOA contact contains `@`, and `intranet` publishes 10.0.4.12. `examples/example.com.fixed.zone` fixes all of them and lints clean (exit 0).

## Rules

- Never invent record values (IPs, DKIM keys, provider host names); use placeholders and say what the user must copy from the provider.
- Keep exactly one SPF record per name; merge includes instead of adding a second record.
- Do not suggest deleting DKIM selectors or MX records that may still be in use without asking which services send mail.
- Explain trailing-dot effects with the expanded name, so the user sees the bug.
- Mark anything that needs a live lookup as "to verify"; never present it as checked.
- Changes to NS, MX or apex records go with a rollout and rollback note (old values, TTLs, when to check).
FILE:references/record-rules.md
# DNS record rules the linter applies

## Names and trailing dots
- In a zone file a name without a final dot is relative: `www` and `mail.example.com` both get the origin appended. `mail.example.com` in zone `example.com.` becomes `mail.example.com.example.com.` - the most common copy-paste bug. Write `mail.example.com.` or just `mail`.
- `@` is the origin (apex). A line starting with whitespace reuses the previous owner name.
- Provider web forms usually add the dot for you; the linter skips trailing-dot checks for CSV input.

## CNAME (RFC 1034 3.6.2, RFC 2181 10.1)
- A name with a CNAME may have no other data (only DNSSEC records). Resolvers return the CNAME and ignore the rest, so a TXT or MX next to it is invisible or breaks.
- The apex always has SOA and NS, so a CNAME at the apex is never valid. Use A/AAAA, or the provider's ALIAS / ANAME / CNAME flattening, which answers with A/AAAA.
- Only one CNAME per name. Chains (CNAME to CNAME) work but cost lookups; keep them short.
- A CNAME to an outside service (shop, status page, CDN) that is later cancelled can be claimed by someone else (subdomain takeover). List them and remove the ones no longer used.

## MX, NS, SRV targets (RFC 2181 10.3, RFC 5321 5.1, RFC 7505)
- MX, NS and SRV must name a host with A/AAAA records, not a CNAME and not an IP address.
- Lower MX preference wins. Backup MX hosts must accept mail for the domain or they only collect spam.
- Null MX `MX 0 .` says the domain receives no mail. It must be the only MX.
- Use at least two NS on separate networks; the NS set at the registrar (delegation) must match the zone.

## SPF (RFC 7208)
- One `v=spf1` TXT record per name. Two records = permerror = SPF fails for all mail.
- Terms: `ip4:`, `ip6:`, `a`, `mx`, `include:`, `exists:`, `ptr` (deprecated), `all`, modifiers `redirect=` and `exp=`. Qualifiers: `+` pass (default), `-` fail, `~` softfail, `?` neutral.
- Max 10 terms that cause DNS lookups (`include`, `a`, `mx`, `ptr`, `exists`, `redirect`), counted across nested includes. `ip4`/`ip6` cost nothing.
- End with `-all` (or `~all` while testing). `+all` lets anyone send as you; `?all` gives no signal. Terms after `all` are ignored.
- The SPF record type (99) is obsolete; publish TXT only.
- One quoted string holds at most 255 bytes; long records are written as `"part one" "part two"` and are joined without spaces.

## DMARC (RFC 7489)
- TXT at `_dmarc.<domain>` only. Must start with `v=DMARC1;` and include `p=none|quarantine|reject`. One record.
- Add `rua=mailto:` to get aggregate reports. Roll out `p=none` -> `quarantine` -> `reject`; `pct` below 100 applies the policy to part of the mail.
- Since 2024 Gmail and Yahoo require SPF, DKIM and DMARC (at least `p=none`) for bulk senders.

## DKIM (RFC 6376, RFC 8301, RFC 8463)
- Keys live at `<selector>._domainkey.<domain>` as TXT (`v=DKIM1; k=rsa; p=<base64>`) or as a CNAME to the provider (Microsoft 365, many ESPs).
- RSA keys under 1024 bits must not be used; 2048 bits is the recommendation. Ed25519 (`k=ed25519`) can be added alongside RSA.
- Empty `p=` means revoked. Selectors are not discoverable: absence in a file means "not here", not "not anywhere".

## TTL and SOA (RFC 1035, RFC 2181 8, RFC 2308)
- TTL is 0..2147483647 s. Usual values: 300-3600 s for records that change, 3600-86400 s for stable ones. Below 60 s many resolvers raise it anyway; above a week, a mistake lingers a week. Lower the TTL a day before a planned change.
- `$TTL` sets the default. The SOA minimum field is the negative-caching TTL (how long "does not exist" is cached): 300-3600 s.
- The SOA contact (rname) is an email written with a dot: `hostmaster.example.com.` for hostmaster@example.com.
- Bump the SOA serial on every change (YYYYMMDDnn).

## Addresses and CAA
- A holds IPv4, AAAA holds IPv6. Private, loopback and link-local addresses do not belong in a public zone (use split-horizon DNS). Documentation ranges (192.0.2.0/24, 2001:db8::/32) are fine in examples.
- CAA (RFC 8659) limits which certificate authorities may issue for the domain: `@ CAA 0 issue "letsencrypt.org"`.
FILE:references/finding-codes.md
# Finding codes

| Code | Sev | Problem | Acceptable when | Usual fix |
|---|---|---|---|---|
| CNAME_AT_APEX | HIGH | apex CNAME conflicts with SOA/NS, breaks mail | never | A/AAAA or provider ALIAS/flattening |
| CNAME_WITH_OTHER_DATA | HIGH | other records next to a CNAME are ignored | DNSSEC records only | move the TXT/MX elsewhere or use A/AAAA |
| MULTIPLE_CNAME | HIGH | two CNAMEs for one name | never | keep one |
| MX_TO_CNAME / NS_TO_CNAME | HIGH | MX/NS/SRV target is an alias | never (some servers tolerate it, many do not) | point at the final A/AAAA host |
| TARGET_IS_IP | HIGH | MX/NS/CNAME value is an IP | never | host name with an A record |
| MISSING_TRAILING_DOT | HIGH | full name without dot gets the origin appended | never | add the dot or write it relative |
| OWNER_DOUBLED_ORIGIN | HIGH | owner `www.example.com` without dot | never | `www` or `www.example.com.` |
| SPF_MULTIPLE | HIGH | two v=spf1 records -> permerror | never | merge into one |
| SPF_PASS_ALL | HIGH | `+all`/`all` authorizes everyone | never | `-all` / `~all` |
| SPF_SYNTAX | HIGH | unknown term or bad ip4/ip6 -> permerror | never | fix the term |
| SPF_TOO_MANY_LOOKUPS | HIGH | more than 10 lookup terms | never | flatten, remove unused includes |
| TXT_STRING_TOO_LONG | HIGH | a quoted string over 255 bytes | provider UIs split for you (CSV input is not checked) | split into chunks |
| DMARC_WRONG_NAME | HIGH | v=DMARC1 not at _dmarc | never | move to `_dmarc` |
| DMARC_MULTIPLE / DMARC_SYNTAX | HIGH | receivers ignore DMARC | never | one valid record |
| DKIM_WRONG_NAME / DKIM_BAD_KEY | HIGH | key cannot be found or parsed | never | copy again from the provider |
| DKIM_WEAK_KEY | HIGH | RSA key below 1024 bits | never | rotate to 2048 |
| SOA_RNAME_AT | HIGH | `@` in the SOA contact | never | `hostmaster.example.com.` |
| NULL_MX_WITH_OTHERS | HIGH | `MX 0 .` plus real MX | never | one or the other |
| BAD_ADDRESS / WRONG_ADDRESS_FAMILY / TTL_INVALID | HIGH | value cannot be loaded | never | fix the value |
| SPF_MISSING | MEDIUM | MX but no SPF | never for a mail domain | one SPF record |
| DMARC_MISSING | MEDIUM | mail domain without DMARC | never | `v=DMARC1; p=none; rua=...` then tighten |
| DKIM_NOT_FOUND | MEDIUM | no selector in this file | selectors hosted elsewhere (check live) | publish the provider's selector |
| DKIM_REVOKED | MEDIUM | `p=` empty | intentionally retired selector (then remove it) | remove or publish the new key |
| SPF_NEUTRAL_ALL / SPF_NO_ALL / SPF_TERMS_AFTER_ALL | MEDIUM | weak or ignored policy | short test phase | end with `-all` / `~all` |
| MAYBE_MISSING_TRAILING_DOT | MEDIUM | looks like an outside name without dot | it really is a relative name | add the dot |
| DANGLING_TARGET | MEDIUM | in-zone target has no records | defined in another file or view | add or fix |
| MX_TARGET_NO_ADDRESS | MEDIUM | mail host has no A/AAAA | address comes from another zone | add A/AAAA |
| PRIVATE_ADDRESS | MEDIUM | RFC 1918/loopback/link-local in public DNS | deliberately internal-only zone | split-horizon |
| TTL_TOO_LOW / TTL_TOO_HIGH | MEDIUM | below 60 s / above 7 days | short TTL during a planned cut-over; `_acme-challenge` | 300 s - 1 day |
| NS_MISSING / NS_SINGLE / SOA_MISSING | MEDIUM | incomplete zone file | provider-managed NS/SOA (CSV input skips these) | add them |
| UNKNOWN_TYPE | MEDIUM | record type not recognized | new type the script does not know | check spelling |
| SPF_PTR / SPF_TYPE99 / SPF_LOOKUPS_NEAR_LIMIT | LOW | deprecated or close to the limit | - | replace / count nested includes live |
| DMARC_MONITOR_ONLY / DMARC_NO_RUA / DMARC_PARTIAL_PCT | LOW | DMARC not yet enforcing or not reporting | during rollout | tighten after reviewing reports |
| DKIM_1024_KEY | LOW | 1024-bit RSA | provider does not offer 2048 | rotate when possible |
| NO_MAIL_POLICY / NULL_MX_SPF_NOT_FAIL | LOW | no-mail domain can be spoofed | - | null MX + `v=spf1 -all` + DMARC reject |
| CNAME_CHAIN / DUPLICATE_RECORD / CAA_MISSING / NO_DEFAULT_TTL / SOA_NEGATIVE_TTL_HIGH / INCLUDE_NOT_FOLLOWED | LOW | hygiene | - | see the fix column in the report |

Exit codes: 0 = no HIGH, 1 = HIGH present, 2 = bad input. In CI, gate on HIGH and keep any `--ignore` list in the repo with a reason.

## Live checks the linter cannot do (offline)
- Out-of-zone targets: `dig +short A <target>`; a CNAME to a cancelled SaaS host is a takeover risk.
- Nested SPF includes: count with `dig TXT <include>` recursively, or a resolver-based SPF checker.
- DKIM selectors hosted by the mail provider: `dig TXT <selector>._domainkey.<domain>` (Google: `google`, Microsoft 365: `selector1`/`selector2` CNAMEs).
- Delegation: `dig NS <domain> @a.gtld-servers.net` (or the TLD's servers) must match the zone's NS set.
FILE:templates/dns-review.md
# DNS review: <domain>

**Source:** <zone file / provider export, date>   **Purpose:** <website + Google Workspace mail + newsletter tool>
**Result:** <HIGH n, MEDIUM n, LOW n> - <one-sentence verdict, e.g. "mail delivery is at risk until SPF is merged and MX is fixed">

## Fix now (HIGH)
| # | Record now | Problem | Replace with |
|---|---|---|---|
| 1 | `<@ CNAME bakery-site.example.net.>` | <CNAME at apex hides MX/TXT> | `<@ A 192.0.2.10>` (or ALIAS at the provider) |
| 2 | `<@ MX 10 mail.example.com>` | <no trailing dot -> mail.example.com.example.com.> | `<@ MX 10 mail.example.com.>` |

## Fix soon (MEDIUM)
- <add `_dmarc` TXT `v=DMARC1; p=none; rua=mailto:dmarc-reports@<domain>`>

## Hygiene (LOW)
- <remove duplicate A for blog; add CAA>

## Mail authentication summary
| Check | Now | After the fix |
|---|---|---|
| SPF | <2 records, ?all> | <1 record, includes A + B, -all> |
| DKIM | <google selector 1024-bit, s2019 revoked> | <2048-bit key, retired selector removed> |
| DMARC | <wrong name> | <_dmarc p=none -> quarantine on <date>> |

## Verify live (not checked offline)
- `<dig +short CNAME shop.<domain>>` - <target still in use?>
- `<dig TXT google._domainkey.<domain>>` - <matches the provider console?>

## Rollout
1. <lower TTL of changed records to 300 s, wait one old TTL>
2. <apply changes, bump SOA serial to YYYYMMDDnn>
3. <verify with dig against the authoritative servers and a public resolver; send a test mail and read the Authentication-Results header>
4. <raise TTLs back to 3600 s; review DMARC reports after 1-2 weeks>

**Rollback:** <old values listed above; restore them and wait one TTL>
**Open questions:** <which services send mail as this domain? is backupmx still used?>
FILE:examples/example.com.zone
; example.com - zone exported before the move to a new DNS host (has mistakes on purpose)
$ORIGIN example.com.
$TTL 3600
@       IN SOA  ns1.example.net. hostmaster@example.com. (
                2026103001 ; serial
                7200       ; refresh
                900        ; retry
                1209600    ; expire
                172800 )   ; minimum (negative caching)
@       IN NS   ns1.example.net.
@       IN NS   ns2.example.net.

; website moved to a static host
@       IN CNAME bakery-site.example.net.
www  30 IN CNAME bakery-site.example.net.
www     IN TXT  "site-verification=4f9c2a"
shop    IN CNAME shops.myshopify.com
blog    IN A    192.0.2.44
blog    IN A    192.0.2.44
legacy 1209600 IN A 192.0.2.45
intranet IN A   10.0.4.12

; mail
@       IN MX 10 mail.example.com
@       IN MX 20 backupmx
backupmx IN CNAME mx2.example.net.
@       IN TXT  "v=spf1 include:_spf.google.com ~all"
@       IN TXT  "v=spf1 include:sendgrid.net ?all"
dmarc   IN TXT  "v=DMARC1; p=none"
google._domainkey IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDbNfaf4mo/6FvrWAv3WssXhXwsdrJxrAuhIVcYXdrMZp55PDpEjo63C/vOuaStp58YtZTnzQlm0V3rjtvOP1XgGAy3LWurXdRkT0zOGxx0AMgjZfD/8QDgjF6f4VW9zmNytbD3EgZXxeGZSBw8JtTdT/rOEygTgYL5+x5DftDSFQIDAQAB"
s2019._domainkey  IN TXT "v=DKIM1; k=rsa; p="
FILE:examples/example.com.fixed.zone
; example.com - corrected zone
$ORIGIN example.com.
$TTL 3600
@       IN SOA  ns1.example.net. hostmaster.example.com. (
                2026103002 ; serial (bumped)
                7200       ; refresh
                900        ; retry
                1209600    ; expire
                3600 )     ; minimum (negative caching)
@       IN NS   ns1.example.net.
@       IN NS   ns2.example.net.
@       IN CAA  0 issue "letsencrypt.org"

; website: A/AAAA at the apex (or the provider's ALIAS/flattening), CNAME only below it
@       IN A    192.0.2.10
@       IN AAAA 2001:db8::10
www     IN CNAME bakery-site.example.net.
_site-verification.www IN TXT "site-verification=4f9c2a"
shop    IN CNAME shops.myshopify.com.
blog    IN A    192.0.2.44
legacy  IN A    192.0.2.45
; intranet moved to the internal (split-horizon) view

; mail
@       IN MX 10 mail.example.com.
@       IN MX 20 mx2.example.net.
mail    IN A    192.0.2.25
@       IN TXT  "v=spf1 include:_spf.google.com include:sendgrid.net -all"
_dmarc  IN TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@example.com"
google._domainkey IN TXT ( "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAz7ouq6bH4GbHRPASRa3m/LiSvOKSZ7L7KZqE231EHY1s8FN9criBQkJXXmxkwPERQSVSyRIC4LjSpxwPTe6LEVhg7nrswTX1ktBbXMUmkgj8CPKV+yWzOsDOMk7kjqghuNWXD/R5K/mT7xbTiCaXztegoQi+"
                           "kVXf0xuMmQYLxVthdjIz1h2PORFhtjzwKYbpaMKjq2BWKIaNtaGBxc2kaSLyPw8W65+A7XeLhtKT8zcteU72IpdmibNsHlkBR0Hb7rQgb+0LgNVqPvF/mm37PKFPQPrfWjjL/Fc1MQoCm8jO3kI0O5ssuP7KKO7ZjtT4ekeHytw23INuPh/Kw1LqzwIDAQAB" )
FILE:examples/lint-report.md
# DNS record lint: example.com.zone

Zone: example.com.   Format: zone   Records: 19   Findings: 19 (HIGH 7, MEDIUM 8, LOW 4)

| Sev | Code | Line | Name | Type | Problem | Fix |
|---|---|---|---|---|---|---|
| HIGH | SOA_RNAME_AT | 4 | @ | SOA | contact 'hostmaster@example.com.' contains '@'; in DNS it is written with a dot | write the contact as hostmaster.example.com. (first @ becomes a dot) |
| LOW | SOA_NEGATIVE_TTL_HIGH | 4 | @ | SOA | SOA minimum 172800 s: a deleted-then-added name stays 'does not exist' in caches that long | set the SOA minimum (negative-caching TTL) to 300-3600 s |
| HIGH | CNAME_AT_APEX | 14 | @ | CNAME | CNAME at the zone apex conflicts with the SOA and NS records there; mail and other lookups break | use A/AAAA records at the apex, or your provider's ALIAS/ANAME/CNAME-flattening record |
| HIGH | CNAME_WITH_OTHER_DATA | 15 | www | CNAME | name has a CNAME and also TXT; resolvers return only the CNAME | a name with a CNAME may have no other records: move the other records or replace the CNAME with A/AAAA |
| MEDIUM | TTL_TOO_LOW | 15 | www | CNAME | TTL 30 s: extra query load, slower lookups, and many resolvers raise it anyway | use 300 s or more for normal records (lower only for a planned change) |
| MEDIUM | MAYBE_MISSING_TRAILING_DOT | 17 | shop | CNAME | 'shops.myshopify.com' looks like a full host name but has no trailing dot, so it means shops.myshopify.com.example.com. | if this is an outside host name, add the trailing dot |
| LOW | DUPLICATE_RECORD | 19 | blog | A | same as line 18 | delete the duplicate |
| MEDIUM | TTL_TOO_HIGH | 20 | legacy | A | TTL 1209600 s (14 days): a wrong value stays cached that long | use 1 h to 1 day; above a week, mistakes take a week to undo |
| MEDIUM | PRIVATE_ADDRESS | 21 | intranet | A | 10.0.4.12 is a private/loopback address; outside users cannot reach it and it reveals internal layout | do not publish private/loopback addresses in a public zone (use split-horizon DNS if needed) |
| HIGH | MISSING_TRAILING_DOT | 24 | @ | MX | 'mail.example.com' has no trailing dot, so it means mail.example.com.example.com. | end fully qualified names with a dot (mail.example.com.) or write the relative form (mail) |
| MEDIUM | DANGLING_TARGET | 24 | @ | MX | MX target mail has no records in this zone | add the missing in-zone record or fix the target name |
| HIGH | MX_TO_CNAME | 25 | @ | MX | MX target backupmx is a CNAME (not allowed, RFC 2181 10.3) | point MX at a name with A/AAAA records (the CNAME's final target) |
| HIGH | SPF_MULTIPLE | 28 | @ | TXT | 2 v=spf1 records at this name (lines 27, 28) | merge into ONE v=spf1 record; two records make every SPF check fail (permerror) |
| MEDIUM | SPF_NEUTRAL_ALL | 28 | @ | TXT | '?all' is neutral: unauthorized senders are not marked | use ~all or -all; ?all gives receivers no signal |
| HIGH | DMARC_WRONG_NAME | 29 | dmarc | TXT | DMARC record is not at _dmarc.<domain>, so receivers never see it | DMARC is only read from _dmarc.<domain>; move the record there |
| LOW | DKIM_1024_KEY | 30 | google._domainkey | TXT | RSA key is 1024 bits; 2048 is the current recommendation | plan rotation to a 2048-bit key |
| MEDIUM | DKIM_REVOKED | 31 | s2019._domainkey | TXT | p= is empty: this selector is revoked and mail signed with it fails DKIM | empty p= revokes the key; remove the record if the selector is retired, or publish the new key |
| MEDIUM | DMARC_MISSING | - | _dmarc | TXT | no DMARC record: receivers cannot tell spoofed mail from yours, and Gmail/Yahoo require DMARC for bulk senders | add TXT at _dmarc: "v=DMARC1; p=none; rua=mailto:dmarc@<domain>" then move to quarantine/reject |
| LOW | CAA_MISSING | - | @ | CAA | no CAA record: any public CA may issue certificates for this domain | optional hardening: CAA 0 issue "<your CA>" limits who may issue certificates |

## Out-of-zone targets to check live (no network calls were made)

| Target | Used by |
|---|---|
| bakery-site.example.net. | @ CNAME (line 14); www CNAME (line 15) |
| mx2.example.net. | backupmx CNAME (line 26) |
| ns1.example.net. | @ NS (line 10) |
| ns2.example.net. | @ NS (line 11) |
| shops.myshopify.com. | shop CNAME (line 17) |
FILE:scripts/dns_lint.py
#!/usr/bin/env python3
"""DNS zone record linter (Python 3.8+ standard library only, works offline).

Reads a BIND-style zone file or a CSV record list exported from a DNS provider and
reports common mistakes before they break web or mail delivery:
CNAME at the apex or next to other records, MX/NS pointing at a CNAME or an IP,
missing trailing dots (mail.example.com -> mail.example.com.example.com.), missing or
duplicate SPF, SPF syntax, +all/?all and the 10-lookup limit, DMARC and DKIM presence
and syntax, weak or revoked DKIM keys, TTL extremes, private addresses in a public
zone, SOA mistakes, duplicate records, and domains that send no mail but have no
"no mail" policy. Out-of-zone targets are listed for a separate live check.

Usage:
  python3 dns_lint.py example.com.zone [--origin example.com] [--json]
        [--min-severity LOW|MEDIUM|HIGH] [--ignore CODE,CODE]
  python3 dns_lint.py records.csv --origin example.com      (CSV columns: name,type,value[,ttl][,priority])
  python3 dns_lint.py --self-test
Zone files: $ORIGIN, $TTL, @, relative names, blank owner (repeat previous), optional
TTL/class in either order, ( ) multi-line records, ; comments, quoted TXT strings.
Exit codes: 0 = no HIGH findings, 1 = HIGH findings, 2 = bad input.
"""
import argparse, base64, csv, io, ipaddress, json, os, re, sys

SEVERITIES = ["LOW", "MEDIUM", "HIGH"]
CLASSES = {"IN", "CH", "HS"}
TYPES = {"A", "AAAA", "CNAME", "MX", "NS", "TXT", "SPF", "SOA", "SRV", "CAA", "PTR", "DNAME",
         "ALIAS", "ANAME", "DS", "DNSKEY", "RRSIG", "NSEC", "NSEC3", "NSEC3PARAM", "HTTPS",
         "SVCB", "TLSA", "NAPTR", "SSHFP", "LOC", "HINFO", "CDS", "CDNSKEY"}
DNSSEC_TYPES = {"RRSIG", "NSEC", "NSEC3", "KEY"}
TARGET_TYPES = {"CNAME": -1, "MX": 1, "NS": 0, "PTR": 0, "DNAME": 0, "SRV": 3, "ALIAS": 0, "ANAME": 0}
COMMON_TLDS = set("com net org edu gov mil int io co dev app ai info biz me tv cloud xyz site online "
                  "shop store tech us uk de fr nl eu es it se no dk fi pl cz at ch be pt ie tr ru "
                  "jp cn kr in au nz ca br mx ar za sg hk tw".split())
INTERNAL_NETS = [ipaddress.ip_network(n) for n in (
    "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10", "127.0.0.0/8", "169.254.0.0/16",
    "0.0.0.0/8", "::1/128", "::/128", "fc00::/7", "fe80::/10")]  # documentation ranges (192.0.2.0/24, 2001:db8::/32) are allowed
SPF_LOOKUP_TERMS = ("include", "a", "mx", "ptr", "exists", "redirect")

FIXES = {
    "CNAME_AT_APEX": "use A/AAAA records at the apex, or your provider's ALIAS/ANAME/CNAME-flattening record",
    "CNAME_WITH_OTHER_DATA": "a name with a CNAME may have no other records: move the other records or replace the CNAME with A/AAAA",
    "MULTIPLE_CNAME": "keep exactly one CNAME for the name",
    "MX_TO_CNAME": "point MX at a name with A/AAAA records (the CNAME's final target)",
    "NS_TO_CNAME": "point NS at the name server's real host name (A/AAAA)",
    "TARGET_IS_IP": "use a host name here and give that host an A/AAAA record",
    "MISSING_TRAILING_DOT": "end fully qualified names with a dot (mail.example.com.) or write the relative form (mail)",
    "MAYBE_MISSING_TRAILING_DOT": "if this is an outside host name, add the trailing dot",
    "OWNER_DOUBLED_ORIGIN": "end the owner name with a dot or write it relative (www)",
    "DANGLING_TARGET": "add the missing in-zone record or fix the target name",
    "CNAME_CHAIN": "point straight at the final name; chains add lookups and break when one link changes",
    "MX_TARGET_NO_ADDRESS": "add A/AAAA records for the mail host",
    "NULL_MX_WITH_OTHERS": "a null MX ('0 .') must be the only MX; remove it or the others",
    "SPF_MISSING": "publish one TXT \"v=spf1 ... -all\" (or ~all while testing) listing every service that sends as this domain",
    "SPF_MULTIPLE": "merge into ONE v=spf1 record; two records make every SPF check fail (permerror)",
    "SPF_TYPE99": "delete the SPF-type record; only the TXT record is used (RFC 7208)",
    "SPF_SYNTAX": "fix the term; one bad term makes the whole record a permerror",
    "SPF_PASS_ALL": "end with -all (or ~all while testing); +all lets anyone send as you",
    "SPF_NEUTRAL_ALL": "use ~all or -all; ?all gives receivers no signal",
    "SPF_NO_ALL": "end the record with -all or ~all (or redirect=)",
    "SPF_TERMS_AFTER_ALL": "move 'all' to the end; terms after it are ignored",
    "SPF_TOO_MANY_LOOKUPS": "flatten or remove includes, drop a/mx/ptr terms you do not need; nested includes count too",
    "SPF_LOOKUPS_NEAR_LIMIT": "count nested includes with a live checker; they add to this number",
    "SPF_PTR": "replace ptr with ip4/ip6 or include (ptr is deprecated and slow)",
    "TXT_STRING_TOO_LONG": "split into quoted chunks of at most 255 characters: \"part1\" \"part2\"",
    "DMARC_MISSING": "add TXT at _dmarc: \"v=DMARC1; p=none; rua=mailto:dmarc@<domain>\" then move to quarantine/reject",
    "DMARC_MULTIPLE": "keep one DMARC record; with two, receivers ignore DMARC entirely",
    "DMARC_SYNTAX": "start with v=DMARC1; and include p=none|quarantine|reject",
    "DMARC_WRONG_NAME": "DMARC is only read from _dmarc.<domain>; move the record there",
    "DMARC_MONITOR_ONLY": "after reviewing reports, move to p=quarantine, then p=reject",
    "DMARC_NO_RUA": "add rua=mailto:... so you get aggregate reports",
    "DMARC_PARTIAL_PCT": "raise pct to 100 once reports look clean",
    "DKIM_NOT_FOUND": "publish the DKIM selector record(s) your mail provider gives you (<selector>._domainkey)",
    "DKIM_WRONG_NAME": "DKIM keys live at <selector>._domainkey.<domain>",
    "DKIM_REVOKED": "empty p= revokes the key; remove the record if the selector is retired, or publish the new key",
    "DKIM_BAD_KEY": "copy the key again from the provider (base64, no spaces or quotes inside)",
    "DKIM_WEAK_KEY": "rotate to a 2048-bit RSA key (or add an ed25519 selector alongside RSA)",
    "DKIM_1024_KEY": "plan rotation to a 2048-bit key",
    "NO_MAIL_POLICY": "for a domain that never sends mail: MX 0 . , TXT \"v=spf1 -all\" and _dmarc \"v=DMARC1; p=reject\"",
    "NULL_MX_SPF_NOT_FAIL": "a no-mail domain should publish \"v=spf1 -all\"",
    "TTL_TOO_LOW": "use 300 s or more for normal records (lower only for a planned change)",
    "TTL_TOO_HIGH": "use 1 h to 1 day; above a week, mistakes take a week to undo",
    "TTL_INVALID": "TTL must be 0..2147483647 seconds",
    "NO_DEFAULT_TTL": "add $TTL at the top of the zone (e.g. $TTL 3600)",
    "SOA_MISSING": "a zone file needs exactly one SOA at the apex",
    "SOA_RNAME_AT": "write the contact as hostmaster.example.com. (first @ becomes a dot)",
    "SOA_NEGATIVE_TTL_HIGH": "set the SOA minimum (negative-caching TTL) to 300-3600 s",
    "NS_MISSING": "list the zone's name servers as NS records at the apex",
    "NS_SINGLE": "use at least two name servers on separate networks",
    "BAD_ADDRESS": "fix the address",
    "WRONG_ADDRESS_FAMILY": "A takes IPv4, AAAA takes IPv6",
    "PRIVATE_ADDRESS": "do not publish private/loopback addresses in a public zone (use split-horizon DNS if needed)",
    "DUPLICATE_RECORD": "delete the duplicate",
    "CAA_MISSING": "optional hardening: CAA 0 issue \"<your CA>\" limits who may issue certificates",
    "UNKNOWN_TYPE": "check the record type spelling",
    "PARSE_ERROR": "fix the line syntax",
    "INCLUDE_NOT_FOLLOWED": "lint the included file separately",
}


class InputError(Exception):
    pass


class Rec:
    __slots__ = ("line", "name", "raw_name", "ttl", "type", "rdata", "raw")

    def __init__(self, line, name, raw_name, ttl, rtype, rdata, raw):
        self.line, self.name, self.raw_name, self.ttl = line, name, raw_name, ttl
        self.type, self.rdata, self.raw = rtype, rdata, raw


def parse_ttl(tok):
    t = tok.lower()
    if t.isdigit():
        return int(t)
    m = re.fullmatch(r"((\d+)[wdhms])+", t)
    if not m:
        return None
    mult = {"w": 604800, "d": 86400, "h": 3600, "m": 60, "s": 1}
    return sum(int(n) * mult[u] for n, u in re.findall(r"(\d+)([wdhms])", t))


def tokenize(text):
    """Split one logical line into tokens; quoted strings keep their quotes."""
    toks, i, n = [], 0, len(text)
    while i < n:
        c = text[i]
        if c.isspace():
            i += 1
        elif c == '"':
            j, buf = i + 1, ['"']
            while j < n and text[j] != '"':
                if text[j] == "\\" and j + 1 < n:
                    buf.append(text[j:j + 2]); j += 2; continue
                buf.append(text[j]); j += 1
            if j >= n:
                raise InputError("unterminated quoted string")
            buf.append('"'); toks.append("".join(buf)); i = j + 1
        else:
            j = i
            while j < n and not text[j].isspace() and text[j] != '"':
                j += 1
            toks.append(text[i:j]); i = j
    return toks


def strip_comment(line):
    out, inq, i = [], False, 0
    while i < len(line):
        c = line[i]
        if c == "\\" and i + 1 < len(line):
            out.append(line[i:i + 2]); i += 2; continue
        if c == '"':
            inq = not inq
        elif c == ";" and not inq:
            break
        out.append(c); i += 1
    return "".join(out)


def logical_lines(text):
    """Yield (line_no, starts_with_space, content) joining ( ... ) groups."""
    buf, start, depth, lead = [], 0, 0, False
    for no, line in enumerate(text.splitlines(), 1):
        body = strip_comment(line)
        if depth == 0:
            if not body.strip():
                continue
            start, lead, buf = no, body[:1].isspace(), []
        inq = False
        clean = []
        for c in body:
            if c == '"':
                inq = not inq
            if not inq and c in "()":
                depth += 1 if c == "(" else -1
                clean.append(" ")
                continue
            clean.append(c)
        buf.append("".join(clean))
        if depth <= 0:
            depth = 0
            yield start, lead, " ".join(buf)
    if depth > 0:
        raise InputError(f"line {start}: '(' is never closed")


def absname(raw, origin):
    if raw == "@":
        return origin
    if raw.endswith("."):
        return raw.lower()
    return (raw + "." + origin).lower() if origin != "." else raw.lower() + "."


def parse_zone(text, origin, findings):
    recs, last_owner, default_ttl, have_ttl_directive = [], None, None, False
    for no, lead, content in logical_lines(text):
        toks = tokenize(content)
        if not toks:
            continue
        if toks[0].upper() == "$ORIGIN":
            if len(toks) < 2:
                raise InputError(f"line {no}: $ORIGIN needs a name")
            origin = absname(toks[1], origin) if not toks[1].endswith(".") else toks[1].lower()
            continue
        if toks[0].upper() == "$TTL":
            v = parse_ttl(toks[1]) if len(toks) > 1 else None
            if v is None:
                raise InputError(f"line {no}: bad $TTL")
            default_ttl, have_ttl_directive = v, True
            continue
        if toks[0].upper() == "$INCLUDE":
            add(findings, "LOW", "INCLUDE_NOT_FOLLOWED", no, "", "", f"$INCLUDE {toks[1] if len(toks) > 1 else ''} was not read")
            continue
        if lead:
            if last_owner is None:
                raise InputError(f"line {no}: record has no owner name and there is no previous one")
            raw_owner = None
        else:
            raw_owner = toks.pop(0)
        ttl, rtype = None, None
        while toks:
            t = toks[0]
            if t.upper() in CLASSES:
                toks.pop(0); continue
            v = parse_ttl(t)
            if v is not None and ttl is None and not t.upper() in TYPES:
                ttl = v; toks.pop(0); continue
            break
        if not toks:
            add(findings, "HIGH", "PARSE_ERROR", no, raw_owner or "", "", f"no record type in '{content.strip()}'")
            continue
        rtype = toks.pop(0).upper()
        if rtype not in TYPES and not re.fullmatch(r"TYPE\d+", rtype):
            add(findings, "MEDIUM", "UNKNOWN_TYPE", no, raw_owner or "", rtype, f"unknown record type '{rtype}'")
        if raw_owner is not None:
            name = absname(raw_owner, origin)
            last_owner = (name, raw_owner)
        name, raw_name = last_owner
        recs.append(Rec(no, name, raw_name, ttl, rtype, toks, content.strip()))
    return recs, origin, default_ttl, have_ttl_directive


def parse_csv(text, origin, findings):
    rows = list(csv.DictReader(io.StringIO(text)))
    if not rows:
        raise InputError("CSV has no rows")
    cols = {c.lower().strip(): c for c in rows[0].keys() if c}
    for need in ("name", "type", "value"):
        if need not in cols:
            raise InputError(f"CSV needs columns name,type,value[,ttl][,priority] (missing '{need}')")
    recs = []
    base = origin.rstrip(".")
    for i, r in enumerate(rows, 2):
        g = lambda k: (r.get(cols[k]) or "").strip() if k in cols else ""
        raw = g("name") or "@"
        low = raw.lower().rstrip(".")
        if raw == "@" or low == base:
            name = origin
        elif low.endswith("." + base):
            name = low + "."
        else:
            name = low + "." + origin
        rtype = g("type").upper()
        value = g("value")
        ttl = parse_ttl(g("ttl")) if g("ttl") else None
        if rtype in ("TXT", "SPF"):
            v = value
            if not v.startswith('"'):
                v = '"' + v.replace('"', '\\"') + '"'
            toks = tokenize(v)
        else:
            toks = value.split()
            if rtype in TARGET_TYPES and toks:  # provider UIs show host names without the dot
                idx = TARGET_TYPES[rtype]
                if rtype == "MX" and len(toks) == 1:
                    toks = [g("priority") or "10"] + toks
                if rtype == "SRV" and len(toks) == 3 and g("priority"):
                    toks = [g("priority")] + toks
                k = len(toks) - 1 if idx == -1 else min(idx, len(toks) - 1)
                if not toks[k].endswith(".") and toks[k] != "@":
                    toks[k] += "."
        recs.append(Rec(i, name, raw, ttl, rtype, toks, ",".join(r.get(c) or "" for c in r)))
    return recs, origin


def add(findings, sev, code, line, name, rtype, problem):
    findings.append({"severity": sev, "code": code, "line": line, "name": name, "type": rtype,
                     "problem": problem, "fix": FIXES.get(code, "")})


def txt_strings(rec):
    out = []
    for t in rec.rdata:
        if t.startswith('"') and t.endswith('"'):
            out.append(re.sub(r"\\(.)", r"\1", t[1:-1]))
        else:
            out.append(t)
    return out


def short(name, origin):
    if name == origin:
        return "@"
    if name.endswith("." + origin):
        return name[: -len(origin) - 1]
    return name


def lint(text, origin=None, fmt=None, filename=""):
    findings = []
    if fmt is None:
        fmt = "csv" if filename.lower().endswith(".csv") or text.lstrip().lower().startswith("name,") else "zone"
    if origin is None:
        m = re.search(r"^\$ORIGIN\s+(\S+)", text, re.M | re.I)
        if m:
            origin = m.group(1)
        elif filename:
            b = os.path.basename(filename)
            for suf in (".zone", ".db", ".txt", ".csv"):
                if b.lower().endswith(suf):
                    b = b[: -len(suf)]
            for pre in ("db.",):
                if b.startswith(pre):
                    b = b[len(pre):]
            origin = b if "." in b else None
        if not origin:
            raise InputError("cannot tell the zone name: add $ORIGIN or pass --origin example.com")
    origin = origin.lower().rstrip(".") + "."
    if fmt == "csv":
        recs, origin = parse_csv(text, origin, findings)
        default_ttl, have_ttl = None, True
    else:
        recs, origin, default_ttl, have_ttl = parse_zone(text, origin, findings)
    base = origin.rstrip(".")
    by_name = {}
    for r in recs:
        by_name.setdefault(r.name, []).append(r)
    types_at = lambda n: {r.type for r in by_name.get(n, [])}
    in_zone = lambda n: n == origin or n.endswith("." + origin)
    externals = {}

    # SOA / NS / TTL
    soa = [r for r in recs if r.type == "SOA"]
    if fmt == "zone":
        if not soa:
            add(findings, "MEDIUM", "SOA_MISSING", 0, "@", "SOA", "no SOA record in the zone file")
        for r in soa:
            if len(r.rdata) >= 7:
                rname = r.rdata[1]
                if "@" in rname:
                    add(findings, "HIGH", "SOA_RNAME_AT", r.line, short(r.name, origin), "SOA", f"contact '{rname}' contains '@'; in DNS it is written with a dot")
                neg = parse_ttl(r.rdata[6])
                if neg is not None and neg > 86400:
                    add(findings, "LOW", "SOA_NEGATIVE_TTL_HIGH", r.line, short(r.name, origin), "SOA", f"SOA minimum {neg} s: a deleted-then-added name stays 'does not exist' in caches that long")
                if default_ttl is None and neg is not None:
                    default_ttl = neg
            else:
                add(findings, "HIGH", "PARSE_ERROR", r.line, short(r.name, origin), "SOA", "SOA needs 7 fields: mname rname serial refresh retry expire minimum")
        ns_apex = [r for r in by_name.get(origin, []) if r.type == "NS"]
        if not ns_apex:
            add(findings, "MEDIUM", "NS_MISSING", 0, "@", "NS", "no NS records at the apex")
        elif len(ns_apex) == 1:
            add(findings, "MEDIUM", "NS_SINGLE", ns_apex[0].line, "@", "NS", "only one name server: if it is down, the whole domain is down")
        if not have_ttl:
            add(findings, "LOW", "NO_DEFAULT_TTL", 0, "", "", "no $TTL directive; records without a TTL fall back to the SOA minimum or the server default")

    for r in recs:
        ttl = r.ttl if r.ttl is not None else default_ttl
        if ttl is None:
            continue
        nm = short(r.name, origin)
        if ttl > 2147483647:
            add(findings, "HIGH", "TTL_INVALID", r.line, nm, r.type, f"TTL {ttl} is above 2147483647")
        elif ttl > 604800:
            add(findings, "MEDIUM", "TTL_TOO_HIGH", r.line, nm, r.type, f"TTL {ttl} s ({ttl // 86400} days): a wrong value stays cached that long")
        elif ttl < 60 and not r.name.startswith("_acme-challenge."):
            add(findings, "MEDIUM", "TTL_TOO_LOW", r.line, nm, r.type, f"TTL {ttl} s: extra query load, slower lookups, and many resolvers raise it anyway")

    # owner names that repeat the origin
    for r in recs:
        if fmt == "zone" and r.raw_name not in (None, "@") and not r.raw_name.endswith(".") and \
                (r.raw_name.lower() == base or r.raw_name.lower().endswith("." + base)):
            add(findings, "HIGH", "OWNER_DOUBLED_ORIGIN", r.line, r.raw_name, r.type, f"owner '{r.raw_name}' has no trailing dot, so it becomes {r.name}")

    # CNAME rules
    for n, rs in by_name.items():
        cn = [r for r in rs if r.type == "CNAME"]
        if not cn:
            continue
        nm = short(n, origin)
        if n == origin:
            add(findings, "HIGH", "CNAME_AT_APEX", cn[0].line, nm, "CNAME", "CNAME at the zone apex conflicts with the SOA and NS records there; mail and other lookups break")
        others = sorted({r.type for r in rs if r.type not in ("CNAME",) and r.type not in DNSSEC_TYPES})
        if others and n != origin:
            add(findings, "HIGH", "CNAME_WITH_OTHER_DATA", cn[0].line, nm, "CNAME", f"name has a CNAME and also {', '.join(others)}; resolvers return only the CNAME")
        if len(cn) > 1:
            add(findings, "HIGH", "MULTIPLE_CNAME", cn[1].line, nm, "CNAME", f"{len(cn)} CNAME records for one name")

    # targets
    for r in recs:
        if r.type not in TARGET_TYPES or not r.rdata:
            continue
        idx = TARGET_TYPES[r.type]
        if r.type == "MX" and len(r.rdata) < 2 or r.type == "SRV" and len(r.rdata) < 4:
            add(findings, "HIGH", "PARSE_ERROR", r.line, short(r.name, origin), r.type, f"{r.type} needs " + ("preference and host" if r.type == "MX" else "priority weight port target"))
            continue
        raw = r.rdata[idx] if idx >= 0 else r.rdata[-1]
        nm = short(r.name, origin)
        if r.type == "MX" and raw == ".":
            continue
        try:
            ipaddress.ip_address(raw.rstrip("."))
            add(findings, "HIGH", "TARGET_IS_IP", r.line, nm, r.type, f"{r.type} target '{raw}' is an IP address; {r.type} must name a host")
            continue
        except ValueError:
            pass
        tgt = absname(raw, origin)
        if fmt == "zone" and raw != "@" and not raw.endswith("."):
            low = raw.lower()
            if low == base or low.endswith("." + base):
                add(findings, "HIGH", "MISSING_TRAILING_DOT", r.line, nm, r.type, f"'{raw}' has no trailing dot, so it means {absname(raw, origin)}")
                tgt = low + "."  # check the name that was meant
            elif "." in low and low.rsplit(".", 1)[1] in COMMON_TLDS:
                add(findings, "MEDIUM", "MAYBE_MISSING_TRAILING_DOT", r.line, nm, r.type, f"'{raw}' looks like a full host name but has no trailing dot, so it means {absname(raw, origin)}")
                tgt = low + "."
        if in_zone(tgt):
            tt = types_at(tgt)
            if r.type in ("MX", "NS", "SRV") and "CNAME" in tt:
                code = {"MX": "MX_TO_CNAME", "NS": "NS_TO_CNAME", "SRV": "MX_TO_CNAME"}[r.type]
                add(findings, "HIGH", code, r.line, nm, r.type, f"{r.type} target {short(tgt, origin)} is a CNAME (not allowed, RFC 2181 10.3)")
            elif r.type == "CNAME" and "CNAME" in tt:
                add(findings, "LOW", "CNAME_CHAIN", r.line, nm, r.type, f"CNAME to {short(tgt, origin)}, which is itself a CNAME")
            elif not tt:
                # wildcard or a deeper/glue name may exist elsewhere; only flag when no wildcard covers it
                wild = "*." + tgt.split(".", 1)[1] if "." in tgt else ""
                if wild not in by_name:
                    add(findings, "MEDIUM", "DANGLING_TARGET", r.line, nm, r.type, f"{r.type} target {short(tgt, origin)} has no records in this zone")
            elif r.type == "MX" and not (tt & {"A", "AAAA"}):
                add(findings, "MEDIUM", "MX_TARGET_NO_ADDRESS", r.line, nm, r.type, f"mail host {short(tgt, origin)} has no A/AAAA record")
        else:
            externals.setdefault(tgt, []).append(f"{nm} {r.type} (line {r.line})")

    # addresses
    for r in recs:
        if r.type not in ("A", "AAAA") or not r.rdata:
            continue
        nm = short(r.name, origin)
        try:
            ip = ipaddress.ip_address(r.rdata[0])
        except ValueError:
            add(findings, "HIGH", "BAD_ADDRESS", r.line, nm, r.type, f"'{r.rdata[0]}' is not an IP address")
            continue
        if (r.type == "A") != (ip.version == 4):
            add(findings, "HIGH", "WRONG_ADDRESS_FAMILY", r.line, nm, r.type, f"{r.type} record holds an IPv{ip.version} address")
        elif any(ip in n for n in INTERNAL_NETS if n.version == ip.version):
            add(findings, "MEDIUM", "PRIVATE_ADDRESS", r.line, nm, r.type, f"{ip} is a private/loopback address; outside users cannot reach it and it reveals internal layout")

    # duplicates
    seen = {}
    for r in recs:
        key = (r.name, r.type, " ".join(x.lower() for x in r.rdata))
        if key in seen:
            add(findings, "LOW", "DUPLICATE_RECORD", r.line, short(r.name, origin), r.type, f"same as line {seen[key]}")
        else:
            seen[key] = r.line

    # TXT string length (zone files only: each quoted string max 255)
    if fmt == "zone":
        for r in recs:
            if r.type in ("TXT", "SPF"):
                for s in txt_strings(r):
                    if len(s.encode()) > 255:
                        add(findings, "HIGH", "TXT_STRING_TOO_LONG", r.line, short(r.name, origin), r.type, f"one quoted string is {len(s.encode())} bytes (max 255); the server rejects the zone or truncates it")
                        break

    # mail: MX, SPF, DMARC, DKIM
    txt_by_name = {}
    for r in recs:
        if r.type == "TXT":
            txt_by_name.setdefault(r.name, []).append((r, "".join(txt_strings(r))))
    for r in recs:
        if r.type == "SPF":
            add(findings, "LOW", "SPF_TYPE99", r.line, short(r.name, origin), "SPF", "SPF-type (99) record is obsolete and ignored")
    spf_at = {}
    for n, items in txt_by_name.items():
        for r, s in items:
            if re.match(r"(?i)v=spf1(\s|$)", s):
                spf_at.setdefault(n, []).append((r, s))
            if re.match(r"(?i)v=dmarc1", s) and not n.startswith("_dmarc."):
                add(findings, "HIGH", "DMARC_WRONG_NAME", r.line, short(n, origin), "TXT", "DMARC record is not at _dmarc.<domain>, so receivers never see it")
            if re.match(r"(?i)v=dkim1", s) and "._domainkey." not in "." + n:
                add(findings, "HIGH", "DKIM_WRONG_NAME", r.line, short(n, origin), "TXT", "DKIM key is not under <selector>._domainkey, so signatures cannot be verified")
    for n, items in spf_at.items():
        nm = short(n, origin)
        if len(items) > 1:
            add(findings, "HIGH", "SPF_MULTIPLE", items[1][0].line, nm, "TXT", f"{len(items)} v=spf1 records at this name (lines {', '.join(str(i[0].line) for i in items)})")
        for r, s in items:
            check_spf(findings, r, s, nm)

    mx_names = {}
    for r in recs:
        if r.type == "MX" and len(r.rdata) >= 2:
            mx_names.setdefault(r.name, []).append(r)
    for n, mxs in mx_names.items():
        nulls = [r for r in mxs if r.rdata[1] == "."]
        if nulls and len(mxs) > 1:
            add(findings, "HIGH", "NULL_MX_WITH_OTHERS", nulls[0].line, short(n, origin), "MX", "null MX ('0 .') next to other MX records")
    apex_mx = [r for r in mx_names.get(origin, []) if r.rdata[1] != "."]
    apex_null = any(r.rdata[1] == "." for r in mx_names.get(origin, []))
    apex_spf = spf_at.get(origin, [])
    spf_sends = any(not re.fullmatch(r"(?i)v=spf1\s+-all", s.strip()) for _, s in apex_spf)
    sends_mail = bool(apex_mx) or spf_sends
    for n, mxs in mx_names.items():
        if any(r.rdata[1] != "." for r in mxs) and n not in spf_at:
            add(findings, "MEDIUM", "SPF_MISSING", mxs[0].line, short(n, origin), "TXT", "name receives mail (MX) but publishes no SPF record")
    if apex_null and apex_spf and spf_sends:
        add(findings, "LOW", "NULL_MX_SPF_NOT_FAIL", apex_spf[0][0].line, "@", "TXT", "null MX says no mail, but SPF still authorizes senders")
    if apex_null and not apex_spf:
        add(findings, "LOW", "NULL_MX_SPF_NOT_FAIL", 0, "@", "TXT", "null MX but no \"v=spf1 -all\"")

    dm = [(r, s) for r, s in txt_by_name.get("_dmarc." + origin, []) if re.match(r"(?i)v=dmarc1", s.strip()) or "p=" in s.lower()]
    dkim_names = [n for n in by_name if n.endswith("._domainkey." + origin)]
    if sends_mail or apex_null:
        if not dm:
            add(findings, "MEDIUM", "DMARC_MISSING", 0, "_dmarc", "TXT", "no DMARC record: receivers cannot tell spoofed mail from yours, and Gmail/Yahoo require DMARC for bulk senders")
    if dm:
        if len(dm) > 1:
            add(findings, "HIGH", "DMARC_MULTIPLE", dm[1][0].line, "_dmarc", "TXT", f"{len(dm)} DMARC records")
        for r, s in dm:
            check_dmarc(findings, r, s)
    if sends_mail and not dkim_names:
        add(findings, "MEDIUM", "DKIM_NOT_FOUND", 0, "*._domainkey", "TXT", "no <selector>._domainkey record: if you send mail, it is probably unsigned (checked only names in this file)")
    for n in dkim_names:
        for r in by_name[n]:
            if r.type == "TXT":
                check_dkim(findings, r, "".join(txt_strings(r)), short(n, origin))
    if not sends_mail and not apex_null and not apex_spf:
        add(findings, "LOW", "NO_MAIL_POLICY", 0, "@", "MX", "no MX and no SPF: if this domain never sends mail, say so, or spammers can spoof it freely")

    has_web = any(r.type in ("A", "AAAA", "CNAME", "ALIAS", "ANAME") for r in recs)
    if has_web and "CAA" not in types_at(origin):
        add(findings, "LOW", "CAA_MISSING", 0, "@", "CAA", "no CAA record: any public CA may issue certificates for this domain")

    order = {s: i for i, s in enumerate(reversed(SEVERITIES))}
    findings.sort(key=lambda f: (f["line"] if f["line"] else 10 ** 6, order[f["severity"]], f["code"]))
    return {"origin": origin, "format": fmt, "records": len(recs), "findings": findings,
            "external_targets": [{"target": t, "used_by": u} for t, u in sorted(externals.items())]}


def check_spf(findings, r, s, nm):
    terms = s.split()[1:]
    lookups, seen_all = 0, None
    for i, t in enumerate(terms):
        q = t[0] if t[0] in "+-~?" else ""
        body = t[len(q):].lower()
        mech = re.split(r"[:=/]", body, maxsplit=1)[0]
        if seen_all is not None and not body.startswith("exp="):
            add(findings, "MEDIUM", "SPF_TERMS_AFTER_ALL", r.line, nm, "TXT", f"'{t}' comes after 'all' and is ignored")
            seen_all = None
        if mech == "all":
            if q in ("", "+"):
                add(findings, "HIGH", "SPF_PASS_ALL", r.line, nm, "TXT", f"'{t}' authorizes every server on the internet to send as this domain")
            elif q == "?":
                add(findings, "MEDIUM", "SPF_NEUTRAL_ALL", r.line, nm, "TXT", "'?all' is neutral: unauthorized senders are not marked")
            seen_all = i
            continue
        if mech in ("include", "exists"):
            if ":" not in body or not body.split(":", 1)[1]:
                add(findings, "HIGH", "SPF_SYNTAX", r.line, nm, "TXT", f"'{t}' needs a domain ({mech}:example.net)")
            lookups += 1
        elif mech in ("a", "mx"):
            lookups += 1
        elif mech == "ptr":
            lookups += 1
            add(findings, "LOW", "SPF_PTR", r.line, nm, "TXT", "'ptr' is deprecated (RFC 7208 5.5)")
        elif mech in ("ip4", "ip6"):
            val = body.split(":", 1)[1] if ":" in body else ""
            try:
                net = ipaddress.ip_network(val, strict=False)
                if (mech == "ip4") != (net.version == 4):
                    raise ValueError
            except ValueError:
                add(findings, "HIGH", "SPF_SYNTAX", r.line, nm, "TXT", f"'{t}' is not a valid {mech} address or range")
        elif mech == "redirect":
            lookups += 1
            if "=" not in body:
                add(findings, "HIGH", "SPF_SYNTAX", r.line, nm, "TXT", f"'{t}': use redirect=domain")
        elif mech == "exp":
            pass
        else:
            add(findings, "HIGH", "SPF_SYNTAX", r.line, nm, "TXT", f"unknown SPF term '{t}' (typo? e.g. ipv4: for ip4:, include= for include:)")
    if not any(re.sub(r"^[+\-~?]", "", t).lower() == "all" for t in terms) and not any(t.lower().startswith("redirect=") for t in terms):
        add(findings, "MEDIUM", "SPF_NO_ALL", r.line, nm, "TXT", "record has no 'all' or redirect=, so unlisted senders get a neutral result")
    if lookups > 10:
        add(findings, "HIGH", "SPF_TOO_MANY_LOOKUPS", r.line, nm, "TXT", f"{lookups} DNS-lookup terms at the top level alone (limit 10, RFC 7208 4.6.4); receivers return permerror")
    elif lookups >= 8:
        add(findings, "LOW", "SPF_LOOKUPS_NEAR_LIMIT", r.line, nm, "TXT", f"{lookups} lookup terms before counting nested includes (limit 10)")


def check_dmarc(findings, r, s):
    tags = {}
    parts = [p.strip() for p in s.split(";") if p.strip()]
    if not parts or parts[0].replace(" ", "").upper() != "V=DMARC1":
        add(findings, "HIGH", "DMARC_SYNTAX", r.line, "_dmarc", "TXT", "record must start with 'v=DMARC1;'")
    for p in parts:
        k, _, v = p.partition("=")
        tags[k.strip().lower()] = v.strip()
    p = tags.get("p", "").lower()
    if p not in ("none", "quarantine", "reject"):
        add(findings, "HIGH", "DMARC_SYNTAX", r.line, "_dmarc", "TXT", "missing or invalid p= (none, quarantine or reject); receivers ignore the record")
        return
    if p == "none":
        add(findings, "LOW", "DMARC_MONITOR_ONLY", r.line, "_dmarc", "TXT", "p=none only monitors; spoofed mail is still delivered")
    if "rua" not in tags:
        add(findings, "LOW", "DMARC_NO_RUA", r.line, "_dmarc", "TXT", "no rua= address, so nobody sees the aggregate reports")
    if tags.get("pct", "100").isdigit() and int(tags.get("pct", "100")) < 100:
        add(findings, "LOW", "DMARC_PARTIAL_PCT", r.line, "_dmarc", "TXT", f"pct={tags['pct']}: the policy applies to only part of the failing mail")


def check_dkim(findings, r, s, nm):
    tags = {}
    for p in s.split(";"):
        k, _, v = p.strip().partition("=")
        if k:
            tags[k.strip().lower()] = re.sub(r"\s+", "", v)
    if "p" not in tags:
        add(findings, "HIGH", "DKIM_BAD_KEY", r.line, nm, "TXT", "no p= tag: not a DKIM key record")
        return
    if tags["p"] == "":
        add(findings, "MEDIUM", "DKIM_REVOKED", r.line, nm, "TXT", "p= is empty: this selector is revoked and mail signed with it fails DKIM")
        return
    try:
        raw = base64.b64decode(tags["p"], validate=True)
    except Exception:
        add(findings, "HIGH", "DKIM_BAD_KEY", r.line, nm, "TXT", "p= is not valid base64 (stray quote, space or cut-off copy?)")
        return
    if tags.get("k", "rsa").lower() == "ed25519":
        return
    bits = rsa_bits(raw)
    if bits is None:
        add(findings, "HIGH", "DKIM_BAD_KEY", r.line, nm, "TXT", f"p= decodes to {len(raw)} bytes but is not an RSA public key (cut off?)")
    elif bits < 1024:
        add(findings, "HIGH", "DKIM_WEAK_KEY", r.line, nm, "TXT", f"RSA key is {bits} bits; keys under 1024 bits are rejected by receivers (RFC 8301)")
    elif bits < 2048:
        add(findings, "LOW", "DKIM_1024_KEY", r.line, nm, "TXT", f"RSA key is {bits} bits; 2048 is the current recommendation")


def der_read(b, i):
    tag = b[i]; i += 1
    ln = b[i]; i += 1
    if ln & 0x80:
        n = ln & 0x7F
        ln = int.from_bytes(b[i:i + n], "big"); i += n
    return tag, i, ln


def rsa_bits(raw):
    """Modulus size of an RSA SubjectPublicKeyInfo (or bare RSAPublicKey) in bits."""
    try:
        tag, i, ln = der_read(raw, 0)
        if tag != 0x30:
            return None
        tag, j, l2 = der_read(raw, i)
        if tag == 0x30:  # SubjectPublicKeyInfo: algorithm, then BIT STRING
            j += l2
            tag, j, l3 = der_read(raw, j)
            if tag != 0x03:
                return None
            j += 1  # unused-bits byte
            tag, j, l4 = der_read(raw, j)
            if tag != 0x30:
                return None
            tag, j, lm = der_read(raw, j)
        elif tag == 0x02:
            lm = l2
        else:
            return None
        if tag != 0x02 or j + lm > len(raw):
            return None
        mod = raw[j:j + lm].lstrip(b"\x00")
        return len(mod) * 8 if mod else None
    except IndexError:
        return None


def render(res, title, min_sev="LOW", ignore=()):
    keep = [f for f in res["findings"] if SEVERITIES.index(f["severity"]) >= SEVERITIES.index(min_sev) and f["code"] not in ignore]
    cnt = {s: sum(1 for f in keep if f["severity"] == s) for s in SEVERITIES}
    out = [f"# DNS record lint: {title}", "",
           f"Zone: {res['origin']}   Format: {res['format']}   Records: {res['records']}   Findings: {len(keep)} (HIGH {cnt['HIGH']}, MEDIUM {cnt['MEDIUM']}, LOW {cnt['LOW']})", ""]
    if keep:
        out += ["| Sev | Code | Line | Name | Type | Problem | Fix |", "|---|---|---|---|---|---|---|"]
        for f in keep:
            out.append(f"| {f['severity']} | {f['code']} | {f['line'] or '-'} | {f['name'] or '-'} | {f['type'] or '-'} | {f['problem']} | {f['fix']} |")
    else:
        out.append("No findings.")
    if res["external_targets"]:
        out += ["", "## Out-of-zone targets to check live (no network calls were made)", "",
                "| Target | Used by |", "|---|---|"]
        for e in res["external_targets"]:
            out.append(f"| {e['target']} | {'; '.join(e['used_by'])} |")
    return "\n".join(out) + "\n", keep


def self_test():
    Z = "$ORIGIN example.com.\n$TTL 3600\n@ IN SOA ns1 hostmaster 1 7200 900 1209600 300\n@ NS ns1\n@ NS ns2.example.net.\nns1 A 192.0.2.53\n"
    MAIL = '@ MX 10 mail\nmail A 192.0.2.25\n@ TXT "v=spf1 mx -all"\n_dmarc TXT "v=DMARC1; p=reject; rua=mailto:d@example.com"\ns1._domainkey CNAME s1.dkim.example.net.\n@ CAA 0 issue "letsencrypt.org"\n'
    k1024 = base64.b64encode(bytes.fromhex("30819f300d06092a864886f70d010101050003818d0030818902818100") + b"\xc1" + bytes(127) + bytes.fromhex("0203010001")).decode()
    k512 = base64.b64encode(bytes.fromhex("305c300d06092a864886f70d0101010500034b003048024100") + b"\xc1" + bytes(63) + bytes.fromhex("0203010001")).decode()

    def codes(text, **kw):
        return [f["code"] for f in lint(text, **kw)["findings"]]

    cases = [
        ("clean zone", Z + MAIL, lambda c: c == []),
        ("cname at apex", Z + MAIL + "@ CNAME shop.example.net.\n", lambda c: "CNAME_AT_APEX" in c),
        ("cname with other data", Z + MAIL + "www CNAME web.example.net.\nwww TXT \"x\"\n", lambda c: "CNAME_WITH_OTHER_DATA" in c),
        ("multiple cname", Z + MAIL + "www CNAME a.example.net.\nwww CNAME b.example.net.\n", lambda c: "MULTIPLE_CNAME" in c),
        ("mx to cname", Z + MAIL.replace("mail A 192.0.2.25", "mail CNAME mx.example.net."), lambda c: "MX_TO_CNAME" in c),
        ("ns to cname", Z.replace("ns1 A 192.0.2.53", "ns1 CNAME dns.example.net.") + MAIL, lambda c: "NS_TO_CNAME" in c),
        ("mx is ip", Z + MAIL.replace("MX 10 mail", "MX 10 192.0.2.25"), lambda c: "TARGET_IS_IP" in c),
        ("missing trailing dot", Z + MAIL + "www CNAME web.example.com\nweb A 192.0.2.80\n", lambda c: "MISSING_TRAILING_DOT" in c),
        ("maybe missing dot (outside name)", Z + MAIL + "shop CNAME shops.myshopify.com\n", lambda c: "MAYBE_MISSING_TRAILING_DOT" in c),
        ("owner doubled origin", Z + MAIL + "www.example.com A 192.0.2.80\n", lambda c: "OWNER_DOUBLED_ORIGIN" in c),
        ("relative target ok", Z + MAIL + "www CNAME web\nweb A 192.0.2.80\n", lambda c: c == []),
        ("dangling target", Z + MAIL + "www CNAME web\n", lambda c: "DANGLING_TARGET" in c),
        ("cname chain", Z + MAIL + "www CNAME web\nweb CNAME edge.example.net.\n", lambda c: "CNAME_CHAIN" in c),
        ("mx target no address", Z + MAIL.replace("mail A 192.0.2.25", "mail TXT \"x\""), lambda c: "MX_TARGET_NO_ADDRESS" in c),
        ("spf missing", Z + MAIL.replace('@ TXT "v=spf1 mx -all"\n', ""), lambda c: "SPF_MISSING" in c),
        ("spf multiple", Z + MAIL + '@ TXT "v=spf1 include:_spf.google.com ~all"\n', lambda c: "SPF_MULTIPLE" in c),
        ("spf +all", Z + MAIL.replace("mx -all", "mx +all"), lambda c: "SPF_PASS_ALL" in c),
        ("spf ?all", Z + MAIL.replace("mx -all", "mx ?all"), lambda c: "SPF_NEUTRAL_ALL" in c),
        ("spf no all", Z + MAIL.replace("mx -all", "mx"), lambda c: "SPF_NO_ALL" in c),
        ("spf terms after all", Z + MAIL.replace("mx -all", "-all mx"), lambda c: "SPF_TERMS_AFTER_ALL" in c),
        ("spf syntax typo", Z + MAIL.replace("mx -all", "ipv4:192.0.2.1 -all"), lambda c: "SPF_SYNTAX" in c),
        ("spf bad ip4", Z + MAIL.replace("mx -all", "ip4:300.1.1.1 -all"), lambda c: "SPF_SYNTAX" in c),
        ("spf too many lookups", Z + MAIL.replace("mx -all", " ".join(f"include:s{i}.example.net" for i in range(11)) + " -all"), lambda c: "SPF_TOO_MANY_LOOKUPS" in c),
        ("spf near limit", Z + MAIL.replace("mx -all", " ".join(f"include:s{i}.example.net" for i in range(8)) + " -all"), lambda c: "SPF_LOOKUPS_NEAR_LIMIT" in c and "SPF_TOO_MANY_LOOKUPS" not in c),
        ("spf ptr", Z + MAIL.replace("mx -all", "ptr -all"), lambda c: "SPF_PTR" in c),
        ("spf type99", Z + MAIL + '@ SPF "v=spf1 mx -all"\n', lambda c: "SPF_TYPE99" in c),
        ("split txt strings joined", Z + MAIL.replace('"v=spf1 mx -all"', '"v=spf1 mx " "-all"'), lambda c: c == []),
        ("txt string too long", Z + MAIL + '@ TXT "' + "a" * 300 + '"\n', lambda c: "TXT_STRING_TOO_LONG" in c),
        ("dmarc missing", Z + MAIL.replace('_dmarc TXT "v=DMARC1; p=reject; rua=mailto:d@example.com"\n', ""), lambda c: "DMARC_MISSING" in c),
        ("dmarc wrong name", Z + MAIL.replace("_dmarc TXT", "dmarc TXT"), lambda c: "DMARC_WRONG_NAME" in c and "DMARC_MISSING" in c),
        ("dmarc multiple", Z + MAIL + '_dmarc TXT "v=DMARC1; p=none"\n', lambda c: "DMARC_MULTIPLE" in c),
        ("dmarc no p", Z + MAIL.replace("p=reject; ", ""), lambda c: "DMARC_SYNTAX" in c),
        ("dmarc none + no rua + pct", Z + MAIL.replace("p=reject; rua=mailto:d@example.com", "p=none; pct=50"), lambda c: {"DMARC_MONITOR_ONLY", "DMARC_NO_RUA", "DMARC_PARTIAL_PCT"} <= set(c)),
        ("dkim not found", Z + MAIL.replace("s1._domainkey CNAME s1.dkim.example.net.\n", ""), lambda c: "DKIM_NOT_FOUND" in c),
        ("dkim revoked", Z + MAIL + 's2._domainkey TXT "v=DKIM1; k=rsa; p="\n', lambda c: "DKIM_REVOKED" in c),
        ("dkim bad base64", Z + MAIL + 's2._domainkey TXT "v=DKIM1; p=MIGf!!"\n', lambda c: "DKIM_BAD_KEY" in c),
        ("dkim 512-bit key", Z + MAIL + f's2._domainkey TXT "v=DKIM1; k=rsa; p={k512}"\n', lambda c: "DKIM_WEAK_KEY" in c),
        ("dkim 1024-bit key", Z + MAIL + f's2._domainkey TXT "v=DKIM1; k=rsa; p={k1024}"\n', lambda c: "DKIM_1024_KEY" in c),
        ("dkim wrong name", Z + MAIL + f's2.domainkey TXT "v=DKIM1; p={k1024}"\n', lambda c: "DKIM_WRONG_NAME" in c),
        ("null mx + spf -all, no mail checks", Z + '@ MX 0 .\n@ TXT "v=spf1 -all"\n_dmarc TXT "v=DMARC1; p=reject; rua=mailto:d@example.com"\n@ CAA 0 issue "letsencrypt.org"\n', lambda c: c == []),
        ("null mx with others", Z + MAIL + "@ MX 0 .\n", lambda c: "NULL_MX_WITH_OTHERS" in c),
        ("no mail policy", Z + '@ CAA 0 issue "letsencrypt.org"\n', lambda c: "NO_MAIL_POLICY" in c),
        ("ttl too low", Z + MAIL + "www 30 A 192.0.2.80\n", lambda c: "TTL_TOO_LOW" in c),
        ("acme ttl low ok", Z + MAIL + '_acme-challenge 30 TXT "token"\n', lambda c: c == []),
        ("ttl too high (units)", Z + MAIL + "www 2w A 192.0.2.80\n", lambda c: "TTL_TOO_HIGH" in c),
        ("no $TTL", Z.replace("$TTL 3600\n", "") + MAIL, lambda c: "NO_DEFAULT_TTL" in c),
        ("soa rname with @", Z.replace("hostmaster", "hostmaster@example.com.") + MAIL, lambda c: "SOA_RNAME_AT" in c),
        ("soa multi-line with comments", Z.replace("@ IN SOA ns1 hostmaster 1 7200 900 1209600 300", "@ IN SOA ns1 hostmaster (\n 2026103001 ; serial\n 7200 900 1209600\n 300 ) ; min") + MAIL, lambda c: c == []),
        ("single ns", Z.replace("@ NS ns2.example.net.\n", "") + MAIL, lambda c: "NS_SINGLE" in c),
        ("bad address", Z + MAIL + "www A 192.0.2.300\n", lambda c: "BAD_ADDRESS" in c),
        ("wrong family", Z + MAIL + "www AAAA 192.0.2.80\n", lambda c: "WRONG_ADDRESS_FAMILY" in c),
        ("private address", Z + MAIL + "intranet A 10.0.0.5\n", lambda c: "PRIVATE_ADDRESS" in c),
        ("duplicate record", Z + MAIL + "www A 192.0.2.80\nwww A 192.0.2.80\n", lambda c: "DUPLICATE_RECORD" in c),
        ("blank owner continues", Z + MAIL + "www A 192.0.2.80\n    AAAA 2001:db8::80\n", lambda c: c == []),
        ("semicolon inside quotes kept", Z + MAIL.replace('"v=DMARC1; p=reject; rua=mailto:d@example.com"', '"v=DMARC1; p=reject; rua=mailto:d@example.com" ; comment'), lambda c: c == []),
        ("caa missing", Z + MAIL.replace('@ CAA 0 issue "letsencrypt.org"\n', ""), lambda c: c == ["CAA_MISSING"]),
        ("csv input", None, None),
        ("unterminated quote is input error", None, None),
    ]
    passed = 0
    for name, text, check in cases:
        try:
            if name == "csv input":
                csvt = ("name,type,value,ttl,priority\n@,MX,mail.example.com,3600,10\nmail,A,192.0.2.25,3600,\n"
                        "@,TXT,v=spf1 include:_spf.google.com ~all,3600,\n@,TXT,v=spf1 mx -all,3600,\n"
                        "www.example.com,CNAME,example.com,300,\n@,CNAME,shop.example.net,300,\n")
                res = lint(csvt, origin="example.com", fmt="csv")
                c = [f["code"] for f in res["findings"]]
                ok = {"SPF_MULTIPLE", "CNAME_AT_APEX", "DMARC_MISSING", "DKIM_NOT_FOUND"} <= set(c) and "MISSING_TRAILING_DOT" not in c and "MX_TO_CNAME" not in c
            elif name == "unterminated quote is input error":
                try:
                    lint(Z + '@ TXT "v=spf1 -all\n')
                    ok, c = False, "no error"
                except InputError as e:
                    ok, c = True, str(e)
            else:
                c = codes(text)
                ok = check(c)
        except Exception as e:  # noqa
            ok, c = False, f"exception {e!r}"
        passed += ok
        print(("PASS " if ok else "FAIL ") + name + ("" if ok else f"  got {c}"))
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Lint a DNS zone file or record list (offline)")
    ap.add_argument("file", nargs="?")
    ap.add_argument("--origin", help="zone name, e.g. example.com (default: $ORIGIN or the file name)")
    ap.add_argument("--format", choices=["zone", "csv"], help="input format (default: by extension/content)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--min-severity", default="LOW", choices=SEVERITIES)
    ap.add_argument("--ignore", default="", help="comma-separated finding codes to skip")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.file:
        ap.error("give a zone file or CSV, or --self-test")
    try:
        with open(a.file, encoding="utf-8") as fh:
            text = fh.read()
        res = lint(text, origin=a.origin, fmt=a.format, filename=a.file)
    except (OSError, InputError, UnicodeDecodeError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    ignore = {c.strip().upper() for c in a.ignore.split(",") if c.strip()}
    md, keep = render(res, os.path.basename(a.file), a.min_severity, ignore)
    if a.json:
        print(json.dumps({**res, "findings": keep}, indent=2))
    else:
        sys.stdout.write(md)
    return 1 if any(f["severity"] == "HIGH" for f in keep) else 0


if __name__ == "__main__":
    sys.exit(main())

Start from the step 2 image "Steaming Outdoor Hot Spring Beside a Snowy Mountain Inn at Blue Hour" as the exact first frame, and animate it into a calm 6-second cinematic shot. Keep the teal hot spring pool, the dark snow-capped rocks around it, the small stone lantern on the left, the larger stone lantern on the right, the two-storey wooden inn with its snowy roofs and warmly lit windows, the snow-laden pine trees, the dark mountain slope, the deep blue twilight sky, and the composition exactly as in the image. The camera makes a slow, gentle push-in toward the pool and the inn. Thick white steam drifts and curls slowly over the water and rises toward the trees. Large soft snowflakes keep falling evenly across the scene. The lanterns and the inn windows glow steadily without flickering. About two thirds of the way through, a small clump of snow slips off a pine branch above the pool and drops straight down into the water near the center, making a small white splash and soft ripples that spread outward and fade. The shot ends calm, with the steam still drifting. Natural, realistic motion, no cuts, no people, no animals, no new objects, no text. Soft sound of bubbling water, a quiet splash, and the hush of falling snow.

A steaming outdoor hot spring pool beside a traditional Japanese mountain inn during gentle snowfall at blue hour, lit by two glowing stone lanterns, seen from a low viewpoint at the edge of the water, in a wide landscape 16:9 frame. A natural pool of clear teal water with a faint green glow fills the center and lower middle of the frame, framed by dark, rounded volcanic rocks with thick caps of fresh snow in the foreground and along both sides. Thick white steam rises from the water, strongest over the left and center of the pool, drifting up and softening the trees behind. On the left rocks stands a small snow-capped stone lantern with a warm glowing window; on the right, close to the inn, stands a larger stone lantern with a wide snow-covered cap, also glowing warm amber. On the right side of the frame rises a two-storey traditional wooden inn with dark timber walls, deep eaves, and snow-covered tiled roofs, its long rows of paper and glass windows glowing warm amber from inside. Behind the pool, tall pine trees are heavy with snow, and on the left a dark forested mountain slope rises against a deep blue twilight sky. Large soft snowflakes fall across the whole scene. Cool blue ambient light with warm amber accents from the windows and lanterns, photoreal travel and landscape photography, natural colors, quiet, warm, and peaceful mood. No people, no text, no logos.

Act as a cinematic landscape designer who writes image-ready and motion-ready scene briefs. Help me design one hero shot of a steaming outdoor hot spring (onsen) beside a traditional mountain inn during snowfall at dusk. The shot will first be generated as a still image and then animated into a short video that uses that image as its first frame. Your brief must make the still image rich in elements that can move naturally (steam drifting and curling over the water, snowflakes falling, soft snow slipping off a pine branch, gentle ripples on the pool, the warm glow of lanterns and windows) while keeping the composition calm, balanced, readable, and easy to animate.

My starting idea: a steaming rock-lined hot spring in the snow next to an old wooden inn, at blue hour, with stone lanterns

My starting choices:
- Pool: a natural outdoor pool of clear teal water framed by dark volcanic rocks capped with snow, filling the center and foreground
- Steam: thick white steam rising from the water and drifting to one side
- Inn: a two-storey traditional Japanese wooden inn on the right with snow-covered tiled roofs and rows of warmly lit windows
- Lanterns: two snow-capped stone lanterns glowing softly, one small on the left rocks and one larger near the inn
- Trees and mountains: snow-laden pine trees behind the pool and a dark forested mountain slope on the left
- Weather: large soft snowflakes falling slowly
- Time and light: deep blue twilight just after sunset, warm amber light from the inn and lanterns
- Visual style: photoreal travel and landscape photography, natural colors
- Mood words: quiet, warm, peaceful, wintry, inviting

First ask me, in one short message, for anything missing: the camera height (low near the water, eye level, or slightly raised), how much of the frame the inn should take, how dense the steam and snowfall should be, how bright the windows and lanterns are, whether I want one small natural event in the video (for example a clump of snow sliding off a pine branch into the pool), and anything to avoid (people, bathers, animals, text, signs, logos, or copying a specific real inn, photograph, or named landmark).

Then produce the brief with these sections:

1. **Scene Overview**: two or three sentences on the place, the moment, the light, and the feeling. Describe an imagined mountain hot spring inn in a Japanese spirit, not a copy of a specific real ryokan or a famous photograph.

2. **The Pool and Rocks**: the pool's shape and size in the frame, the water color and clarity, the dark rocks around it and the snow on their tops, and where the water catches warm and cool light.

3. **Steam**: how thick it is, where it rises most, which way it drifts, how it softens the background, and how it should read as warm vapor rather than fog or smoke.

4. **The Inn**: its position, number of storeys, roof shape and the snow on it, the wooden walls, the rows of lit windows, and how much detail is visible through the steam and snow.

5. **Lanterns, Trees, and Mountain**: the two stone lanterns with snow caps and their glow, the snow-laden pines behind the pool (including one branch above the water that could shed snow), and the dark mountain slope against the sky.

6. **Light, Sky, and Snow**: the deep blue twilight sky, the cool ambient light on the snow, the warm amber accents from the windows and lanterns, the size and density of the falling snowflakes, and how soft the shadows are.

7. **Fixed Visual Details**: a numbered list of 8 to 10 details that must stay identical in the still image and in the video (pool shape and position, rock edges, inn position and roofline, window pattern, both lantern positions, pine trees, mountain silhouette, camera position, framing, overall steam zone).

8. **Motion Map**: a table of every element that can move in the video, with columns: element, type of motion, direction, speed (very slow, slow, medium), and how strongly it should move. Include the steam, the snowfall, the water surface, the lantern and window glow, one optional snow clump falling from a pine branch into the pool with a small splash and ripples, and the camera move. Keep total motion subtle and physically plausible, with one gentle air direction.

9. **Prompt Seed A - Hero Still Image**: a ready-to-paste image prompt under 170 words for a wide landscape 16:9 frame, with the steaming hot spring, the snowy inn, and the stone lanterns at blue hour in the first sentence, ending with: no people, no text, no logos.

10. **Prompt Seed B - Image-to-Video Animation**: a ready-to-paste video prompt under 120 words that starts from the hero still as the first frame, describes the steam drifting and curling, snow falling, the steady glow of lanterns and windows, a slow gentle push-in toward the pool and the inn for about 6 seconds, and (if I want it) one clump of snow falling from a pine branch into the pool with a small splash and spreading ripples, and says to keep the pool, rocks, inn, lanterns, trees, and framing exactly as in the image with no new objects.

Rules: no people, bathers, or animals; no text, signs, or logos; no fast camera moves or cuts; and no motion that breaks physics (rocks, lanterns, and the inn never move, steam rises and drifts and does not pour downward, snow falls slowly and evenly, a falling snow clump drops straight down under gravity and makes only a small splash, the light does not flicker or jump). Use short paragraphs and lists.