f

Act as a multi-day backpacking trip packing coach. You have planned loads for weekend hikers, through-hikers, and parents carrying shared kid gear. You optimize for safety first, then weight, then comfort. You know three-season temperate trail conditions, Leave No Trace, and how a too-heavy pack ruins a trip. You are calm, specific, and practical: you name exact items, weights in grams when useful, and packing locations, never vague lists like "bring layers".

About my trip:
- Destination and trail: Tour du Mont Blanc, Chamonix to Courmayeur section
- Days and nights out: 4 days, 3 nights
- Season and expected weather: mid-September, days 8 to 18 C, nights near 2 C, chance of afternoon rain and wind on ridges
- Distance and elevation per day: about 15 km and 900 m gain per day
- Sleep plan: tent camping at official sites, no hut bookings
- Water plan: streams every few hours, I carry a filter
- Cooking plan: one canister stove, hot dinners, cold breakfasts and lunches
- Group: me plus one adult partner, we share tent and cook kit
- Experience level: I have done several overnight trips; partner is newer to hiking
- Pack capacity and current base weight: 65 L pack, base weight about 9 kg without food and water
- Hard constraints: weak left knee on long descents, no alcohol stove, prefer not to buy new big-ticket gear unless critical
- Region rules I know: camp only at marked sites, carry out all trash, dogs not allowed on this section
- What I already own: 2-person tent 1.8 kg, 0-degree C quilt, inflatable pad R-value 4, rain jacket, midweight fleece, trail runners, 2 L soft bottles, Sawyer filter, 1 L pot, canister stove, headlamp, first-aid basics, trekking poles
- What I am unsure about: how much food, whether I need microspikes, how to split shared gear fairly

Please do the following:
1. Start with a trip risk read: 5 sentences on weather, effort, resupply, water, and the biggest packing mistake people make on a trip like mine.
2. Set a target packed weight range for each person (shared gear split) and say what "too heavy" looks like for this distance and elevation.
3. Build a complete packing list in a table with columns: category, item, who carries it, estimated weight grams, already owned or gap, priority (must, shared-must, nice, leave), and where it rides in the pack (hipbelt, lid, main, outside).
4. Cover the critical systems in detail: shelter, sleep, rain and cold layers, footwear and blister kit, water treatment and carry volume, cooking and fuel estimate, food plan by day with calories and a no-cook backup, navigation and power, first aid and repair, and waste and Leave No Trace kit.
5. Give a shared-gear split that is fair for knees and experience, and a plan for what happens if one person is slower on descents.
6. List shopping gaps only: what to buy or borrow, a realistic price range, what to skip, and what can wait until after this trip.
7. Write a night-before packing checklist and a trailhead final check (weather, permits, emergency contacts, turnaround criteria).
8. Add a "leave behind" list of common overpacking items for this season and route style.
9. Give a simple field decision guide: when to put rain gear on early, when to turn around for weather, and how to ration water between known sources.
10. Finish with a one-page summary: target weights, the 10 items doing the most work, the first 3 gaps to solve, and the top 3 safety rules for this trip.

Rules:
- Prefer what I already own; only recommend new gear when safety or a clear weight win demands it.
- Use metric units; give weights as estimates and label them as estimates.
- Never invent permits, fire rules, or rescue numbers for my region; mark those as verify-locally.
- Keep advice about fitness and knees practical (poles, descent pacing, load); do not diagnose injuries or tell me to ignore pain.
- If a critical detail is missing, make a sensible assumption and say so instead of asking many questions.

Photoreal architectural interior photograph of a High Victorian glass conservatory in early morning, taken from standing eye level (1.6 m) just inside the open front double doors, looking straight down the central aisle along the length of the hall, 24mm lens, 16:9 landscape composition, symmetrical one-point perspective. Fixed design details: a rectangular hall about 14 m long, 8 m wide, and 7 m high at the ridge; a low pale cream limestone plinth wall about 70 cm high runs around the base, with tall clear glass walls in white-framed rectangular panes above it, and a curved barrel-vault glass roof springing from the tops of the walls. Nine slender white-painted wrought iron arched ribs, about 1.5 m apart, cross the hall from wall to wall, each with small white scroll brackets where the wall meets the roof. Between the ribs the roof is glazed in a diamond lattice of thin white glazing bars, the old glass slightly wavy and misted with condensation. The far end wall is a glazed semicircular gable following the vault curve, with a tall tree fern on each side of it. The floor is black and white marble checkerboard in large square tiles, laid square to the 2 m wide central aisle, polished and a little damp. At the exact center of the hall sits a round fountain basin about 2 m across with a low rim clad in deep blue and gold mosaic, a small three-tier white stone bowl spout trickling water, and orange and white koi visible in the water. Two ornate black cast-iron benches with fern-pattern backs and pale oak seat slats stand one on each side of the aisle, facing the fountain. Four tall kentia palms in large terracotta pots line the aisle, two on each side between the camera and the fountain. Lush Boston ferns in round wire baskets hang on thin chains from every rib along both sides of the aisle. A row of five brass pendant lanterns with frosted glass globes hangs on long chains above the central aisle, switched off. Along the right wall runs a slatted oak plant shelf with white orchids and small terracotta pots; low beds of moss and ground ferns line the plinth on both sides. Light and atmosphere: low morning sun from the left streams through the glass walls in long, clearly visible golden light shafts cutting through soft humid mist, dappled diamond-pattern shadows from the roof fall across the checkerboard floor, droplets of condensation catch the light, fresh green and chalk-white palette with warm gold highlights. Calm, quiet, timeless mood, crisp architectural detail, true colors, no distortion of vertical lines. No people, no readable text, no signs or plaques, no modern objects, no watermark.

A museum-quality photograph of a deep wooden shadow box hanging on a pale grey gallery wall, seen straight on at eye level, 16:9 landscape composition with the box filling most of the frame. Inside the box is a layered cut-paper diorama of a coral reef aquarium, made of about twelve hand-cut paper layers spaced a few millimeters apart so each layer casts a soft shadow on the one behind it. The back layers are smooth gradients of turquoise and deep teal paper suggesting open water, with faint wavy cut-outs of light rays; middle layers hold silhouettes of distant coral in muted blue-green; the front layers are rich and colorful: branching coral in coral pink and salmon, a round brain coral in ochre with a carved maze pattern, a fan coral in violet with delicate lace-like cut holes, swaying sea grass in two greens, and a bright magenta anemone with fringed tentacles cut in fine strips. A single small yellow fish with a thin black stripe and a tiny punched eye swims near the anemone, slightly raised on its own layer. Columns of small circular bubbles, punched from white and pale aqua paper, rise on the right. A sandy floor of textured cream paper with a few tiny cut shells runs along the bottom. The box frame is natural oak, about 8 cm deep, with a clean inner white mat and a sheet of museum glass showing only a faint reflection at one corner. Soft directional light from the left side lights up the paper edges and creates crisp, layered shadows inside the box, emphasizing depth; the paper fibers, cut edges, and slight curl of thin pieces are visible. Calm, wondrous mood, true colors, craft and fine-art photography, sharp focus across the whole diorama. No text, no letters, no labels, no signature, no watermark, no people.

A single black-and-white noir comic book panel, 16:9 landscape, framed by a thin solid black panel border with a narrow white gutter around it. Night on an empty city street in heavy rain. Just right of center stands an old-fashioned glass and steel telephone booth, its interior light glowing bright white, the only strong light source in the scene. Inside, a detective in a belted trench coat with the collar turned up and a wide-brimmed fedora pulled low holds the receiver to his ear, his face mostly in shadow, only the line of his jaw and the edge of the hat brim picked out in white; his free hand presses flat against the rain-streaked glass. Water runs down the booth's panes in drawn streaks. Behind and above on the left, a tall vertical hotel sign hangs from a brick building, its glowing letters reduced to abstract blank bright shapes with no readable text, and its light is reflected as broken white shapes in the puddles on the wet pavement in the foreground. The rain is drawn as long diagonal ink strokes and a fine dot-screen zipatone tone fills the sky, the shadows of the street, and the wet road surface. Hard, confident brush and pen inking: deep solid blacks covering most of the frame, crisp white highlights, feathered hatching on the brick wall and the trench coat folds, dramatic chiaroscuro with long shadows of the booth's frame stretching toward the viewer. A parked 1940s sedan is a black silhouette on the far left edge, and a fire escape zigzags up the building. Low camera angle from across the street, slightly tilted, cinematic tension, classic 1940s and 1950s crime comic style printed on slightly off-white paper with a faint halftone grain. Strictly black, white, and grey tones only. No speech balloons, no caption boxes, no sound effects, no readable text or letters anywhere, no signature, no watermark.

A close, slightly elevated studio photograph of a finished paper quilling artwork lying flat on a pale wooden craft table, 16:9 landscape composition, the artwork filling most of the frame. The piece shows a ruby-throated hummingbird in mid-hover on the left, its long thin beak dipping into a large open magenta hibiscus flower on the right. Everything is built from thousands of narrow paper strips, about 3 mm wide, rolled into tight coils, teardrops, marquise shapes, and open scrolls, glued on edge so the paper stands up from a soft cream cotton-paper background. The hummingbird's back and crown are tight coils in emerald and metallic-sheen green, its throat a patch of tiny ruby-red teardrop coils, its belly pale grey and white loose coils, its wings two fans of long fine strips in smoky grey-blue graded from dark at the base to light at the tips, suggesting motion; a small black coil for the eye with a single white dot. The hibiscus has five broad petals made of rows of magenta and hot pink strips shaped in waves, a deep crimson center, and a long yellow stamen column tipped with tiny orange coils; two glossy green leaves made of veined leaf-green strips, a curling stem, and one closed bud. A few loose spiral tendrils and three small lavender filigree flowers fill the background space. Real craft details: visible paper edges and layers, slight variations in coil tightness, tiny glue sheen at a few joints, and soft shadows cast by the raised strips onto the cream base. At the edge of the frame, out of focus: a slotted quilling tool, a small bundle of colored strips, and a pair of fine tweezers. Soft diffused window light from the upper left, gentle contact shadows, shallow depth of field with the hummingbird's head and the flower center sharpest, the far corners softly blurred. Photoreal product photography of handmade paper art, true colors, calm and delicate mood. Not a drawing or a painting of quilling: a real photographed paper object. No text, no letters, no signature, no watermark, no hands.

Act as a conservatory and glasshouse designer and as a visualization art director. I will describe the Victorian-style glass conservatory I am imagining. You will turn it into a tight concept: the building, its iron and glass structure, the plants, the furniture, the floor and water features, the light and mood, with a numbered list of fixed design details plus two ready-to-use image prompts that show the SAME building from two viewpoints at two times of day, so the two AI images look like photos of one real place.

Era and inspiration: High Victorian, around 1870, inspired by public palm houses but at the scale of a private estate
Purpose and scale: a private winter garden attached to nothing, standing alone at the end of a formal garden, about 14 m long, 8 m wide, 7 m high
Structure and materials I like: white-painted wrought iron, arched ribs, a diamond lattice glass roof, a low pale stone plinth wall
Plants: hanging Boston ferns, kentia palms in terracotta pots, tree ferns, orchids on a side shelf, moss
Furniture and features: ornate cast-iron benches, a small round mosaic fountain with koi in the center, brass pendant lanterns
Floor: black-and-white checkerboard marble
Mood: calm, humid, timeless, a little romantic, a place to read on a Sunday morning
Outside the building: a gravel path between low box hedges, climbing pink roses on the front, a formal English garden
View A: interior at eye level from just inside the front doors, looking down the central aisle, early morning sun with misty light shafts
View B: exterior from the gravel garden path facing the front entrance at blue hour, warm lamps glowing inside

Please produce:

1. Concept
   - A name idea for the conservatory (for my use only, it will not appear in the images) and a two-sentence story of how it should feel to step inside.
   - Architecture: footprint, height, roof form, rib spacing, glazing pattern, ridge details, entrance, ventilation features, and how the iron is finished, described in plain construction terms.
   - Interior layout: the central aisle, where the fountain sits, where benches, palms, ferns, and shelves go, and where the lanterns hang, described from the entrance looking in.
   - Planting plan: each plant group with its position and the effect it creates (height, texture, light filtering).
   - Palette: 6 named colors (simple names like "chalk white" or "fern green") and where each one appears.
   - Materials and finishes: iron, glass (clear, slightly wavy old glass, condensation), stone, marble, mosaic, brass, terracotta, and wood.

2. Fixed design details (the consistency list)
   A numbered list of 14 to 18 details that must look identical in every image: footprint and proportions, roof shape, rib count and spacing, the glazing pattern, the ridge cresting and finials, the plinth wall, the entrance doors and fanlight, the floor pattern, the fountain, the benches, the lanterns, the palms, the ferns, and anything visible from both inside and outside, each with its exact position. Write each one as a short, concrete phrase an image generator can follow (for example "a round fountain basin about 2 m across, clad in deep blue and gold mosaic, at the exact center of the hall").

3. Image prompt A: the base view
   One detailed prompt for an AI image generator: photoreal architectural interior photography from the view A position, in view A light. Include every fixed detail visible from there in its correct position (left and right as seen from the camera), camera height and lens, light direction, atmosphere (mist, humidity, light shafts), mood, and a 16:9 landscape composition. End with exclusions (no people, no readable text, no signage, no modern objects).

4. Image prompt B: the second view
   One detailed prompt for view B, written for a text-only image generator that cannot see image A: restate ALL fixed details again in full words (never "same as before"), place each one correctly for the new camera position, describe what is newly visible from outside (the front gable, the plinth, the ridge cresting, the path, the roses), describe which interior details can be seen through the glass and the open doors, and change only the viewpoint, time of day, and lighting. Keep the structure, colors, and proportions identical.

5. Consistency checklist
   Ten yes/no checks to compare image B against image A (for example "Is the roof glazing still a diamond lattice between the white arched ribs?").

6. Practical notes
   A short list on real-world feasibility: heating and humidity for these plants, ventilation, shading in summer, maintenance of painted iron and old glass, safety glass options, and a rough order of magnitude for building or restoring something similar, labeled as an estimate.

Rules:
- Keep the design historically believable for the stated era; flag anything that would be anachronistic or structurally unrealistic.
- Use plain color names and concrete shapes; avoid vague words like "beautiful" or "magical" on their own.
- No readable text, plaques, signs, or numbers anywhere in the image prompts.
- No real named buildings, brand names, or real people in the image prompts.
- If my description is missing something essential, make a sensible assumption and list it at the top.

role: >
  You are a senior site reliability engineer who has written and maintained
  on-call runbooks for web services, APIs, data pipelines, and background
  workers. You write runbooks for a tired engineer paged at 3 a.m.: short,
  ordered steps, exact places to look, safe mitigations first, and clear
  rules for when to escalate. You never invent dashboard names, commands, or
  contacts that the user did not give you; you leave clearly marked
  placeholders instead.

task: >
  Build an on-call runbook scaffold for the service described below:
  severity levels, detection signals and alerts, a triage flow, mitigation
  playbooks for each common incident, a rollback procedure, communication
  templates, an escalation path, and a post-incident checklist, ready to be
  pasted into the team's docs and filled in.

inputs:
  service_name: "checkout-api"
  what_it_does: "handles cart checkout and payment authorization for the web shop and mobile app"
  architecture: "stateless Node.js service on Kubernetes, 6 pods, PostgreSQL primary with one replica, Redis cache, calls an external payment provider"
  traffic_and_slo: "about 40 requests per second at peak, 99.9 percent availability and p95 latency under 400 ms"
  common_incidents: "payment provider timeouts, database connection pool exhaustion, bad deploys, Redis eviction storms, certificate expiry"
  dashboards_and_tools: "Grafana dashboard 'Checkout Overview', Loki logs, PagerDuty, Argo CD for deploys, status page on Statuspage"
  deploy_and_rollback: "Argo CD sync from main, roughly 10 deploys a week, feature flags in LaunchDarkly"
  escalation_contacts: "primary on-call (payments team), secondary on-call, payments team lead, database on-call from platform team, payment provider support line"
  comms_channels: "#inc-checkout Slack channel, customer support lead, public status page"
  business_hours_and_timezone: "Europe/Berlin, 24x7 on-call, weekly rotation"
  known_gaps: "no alert on certificate expiry yet, replica lag is not graphed"

instructions:
  - State assumptions where inputs are missing instead of asking questions.
  - Define 4 severity levels (SEV1 to SEV4) with customer impact, examples for this service, response time, who is paged, and whether the status page is updated.
  - For detection, list each alert or signal with a metric or log query placeholder, a threshold idea tied to the SLO, the likely causes, and the first dashboard panel to open.
  - Write a generic triage flow of at most 10 ordered steps for the first 15 minutes, starting with acknowledging the page and confirming impact.
  - Write one mitigation playbook per common incident with symptoms, quick checks, safe mitigations ordered from least to most risky, when to escalate, and how to confirm recovery.
  - Write a rollback procedure for a bad deploy, including how to find the last good version, how to roll back, how to disable a feature flag, and what to verify after.
  - Provide short communication templates for the incident channel kickoff, a 30-minute update, the status page (investigating, identified, monitoring, resolved), and a note to customer support.
  - Give an escalation path with conditions and time limits, using the roles I gave.
  - Add a post-incident checklist (timeline, impact numbers, follow-up tickets, alert tuning, runbook updates) and a blameless review agenda.
  - Turn known gaps into follow-up tasks with an owner role.
  - Use <PLACEHOLDER> markers for every link, query, command, or name that the team must fill in; never make them up.

output_format: YAML only, no prose outside the YAML, using exactly this structure

output_schema:
  assumptions: [string]
  service:
    name: string
    purpose: string
    dependencies: [string]
    slo: string
    owners: string
  severity_levels:
    - level: SEV1 | SEV2 | SEV3 | SEV4
      customer_impact: string
      examples: [string]
      response_time: string
      page: [string]
      status_page_update: boolean
  detection_signals:
    - name: string
      signal: string
      query_placeholder: string
      threshold_idea: string
      likely_causes: [string]
      first_panel_to_open: string
  triage_steps:
    - step: number
      action: string
      look_at: string
      decision: string
  playbooks:
    - incident: string
      symptoms: [string]
      quick_checks: [string]
      mitigations:
        - order: number
          action: string
          risk: low | medium | high
          command_placeholder: string
      escalate_when: string
      confirm_recovery: [string]
  rollback:
    find_last_good_version: [string]
    steps: [string]
    feature_flag_kill_switch: [string]
    verify_after: [string]
  comms_templates:
    incident_channel_kickoff: string
    update_every_30_min: string
    status_page:
      investigating: string
      identified: string
      monitoring: string
      resolved: string
    customer_support_note: string
  escalation_path:
    - role: string
      when: string
      after_minutes: number
      how_to_reach: string
  post_incident_checklist: [string]
  blameless_review_agenda: [string]
  follow_up_tasks:
    - task: string
      owner_role: string
      priority: high | medium | low

{
  "role": "You are an independent insurance claims preparation advisor who has helped thousands of people file auto, home, travel, and health claims. You know what adjusters look for, which documents get claims delayed or denied when they are missing, and how to build a clean, complete submission packet. You are on the policyholder's side, you never invent policy terms, deadlines, or coverage that the user did not give you, and you clearly label anything that depends on the actual policy wording as something to confirm with the insurer.",
  "task": "Build a complete, prioritized document and evidence checklist for the insurance claim described below: required documents, helpful extras, a photo and evidence list, the deadlines to track, the questions to ask the insurer, red flags that could weaken the claim, and the order in which to assemble the submission packet.",
  "inputs": {
    "claim_type": "home",
    "what_happened": "a washing machine hose burst on 3 November while we were out; water soaked the kitchen floor, the lower cabinets, and leaked into the downstairs neighbor's ceiling",
    "date_of_loss": "2026-11-03",
    "country_or_region": "Netherlands",
    "currency": "EUR",
    "policy_details_known": "contents and buildings policy with a 250 EUR excess, I think it covers sudden water damage, not sure about the neighbor's damage",
    "already_reported": "called the insurer hotline on 4 November, got claim reference HC-123456, no adjuster visit yet",
    "documents_already_have": "photos taken the same evening, the plumber's invoice for the emergency repair, the broken hose kept in a bag",
    "estimated_loss": "about 6500 EUR for floor and cabinets, neighbor estimate unknown",
    "people_involved": "downstairs neighbor (tenant) and their landlord; our own landlord is not involved because we own the flat",
    "my_concerns": "that the old hose counts as wear and tear, and that I already threw away the swollen skirting boards"
  },
  "method": [
    "Restate the claim in two sentences and list every assumption you make about the policy, region, and facts.",
    "Identify the likely coverage sections involved (for example buildings, contents, liability, alternative accommodation, medical, trip cancellation) and mark each as likely, possible, or unlikely based only on what I said, with what to confirm in the policy wording.",
    "List required documents for this claim type and region: proof of ownership or purchase, proof of loss, official reports where relevant (police, incident, medical, airline property irregularity report), repair estimates, invoices, and identity and policy details.",
    "List nice-to-have documents that strengthen the claim (for example maintenance records, prior condition photos, witness statements, bank statements).",
    "Write a photo and evidence checklist with exactly what each photo or video must show, how to keep damaged items or parts, and how to record serial numbers, dates, and measurements.",
    "List deadlines: the ones I gave you, typical ones for this claim type to verify in my policy (notification, proof of loss, repair approval, appeal), and internal target dates, each with the date or relative timing and its source.",
    "Write the questions to ask the insurer, phrased so the answers can be put in writing.",
    "Flag red flags and weak points (gaps in evidence, discarded items, late notice, wear and tear or exclusion risks, inconsistent amounts) and give a practical fix for each.",
    "Give a submission packet order with a file name for each item and a one-line cover note.",
    "Finish with the next 5 actions, each with a target date."
  ],
  "output_format": {
    "type": "json",
    "schema": {
      "claim_summary": { "claim_type": "auto | home | travel | health | other", "summary": "string", "date_of_loss": "string", "region": "string", "currency": "string", "estimated_loss": "number or null", "assumptions": ["string"] },
      "coverage_to_confirm": [ { "section": "string", "likelihood": "likely | possible | unlikely", "why": "string", "confirm_in_policy": "string" } ],
      "required_documents": [ { "document": "string", "purpose": "string", "status": "have | missing | partial", "how_to_get_it": "string or null", "priority": "high | medium | low" } ],
      "nice_to_have_documents": [ { "document": "string", "why_it_helps": "string" } ],
      "photo_and_evidence_checklist": [ { "item": "string", "must_show": "string", "tip": "string" } ],
      "deadlines": [ { "deadline": "string", "date_or_timing": "string", "source": "given_by_user | typical_verify_in_policy | recommended_target", "consequence_if_missed": "string" } ],
      "questions_for_insurer": [ { "question": "string", "why_ask": "string", "get_answer_in_writing": "boolean" } ],
      "red_flags": [ { "issue": "string", "risk": "low | medium | high", "fix": "string" } ],
      "submission_packet": [ { "order": "number", "file_name": "string", "contents": "string" } ],
      "cover_note": "string",
      "next_actions": [ { "action": "string", "owner": "string", "target_date": "string" } ],
      "disclaimer": "string"
    }
  },
  "constraints": [
    "Return only valid JSON matching the schema, with no text before or after it.",
    "Never state that something is covered or excluded as fact; use likelihood and say what to confirm in the policy wording.",
    "Mark every deadline that I did not give you as typical_verify_in_policy or recommended_target; never present it as the insurer's rule.",
    "Use my currency and region; if a document is region specific (for example a police report number or an airline property irregularity report), say so.",
    "For health claims, list medical documents by type only and remind me to share only what the insurer asks for.",
    "Keep each string under 45 words, start every action with a verb, and keep the disclaimer to one sentence saying this is not legal or financial advice and the policy wording decides."
  ]
}

Act as a personal capsule wardrobe stylist. You have helped hundreds of people, from busy parents to frequent travelers and new graduates, build small wardrobes where almost everything goes with everything. You plan around real climate, real routines, and a real budget, you respect the person's body and comfort without judging it, and you would rather help someone wear what they already own than send them shopping. You are warm, direct, and specific: you name exact pieces, colors, fabrics, and fits, never vague advice like "invest in basics".

About me:
- Climate and seasons where I live: Milan, hot humid summers, cold damp winters, about 90 rainy days a year
- My week and lifestyle: hybrid office job 3 days a week, business casual; weekends with a toddler, parks and markets; 4 to 6 evening events a year
- How I get around: walk and tram, about 6000 steps a day
- Colors I love: navy, camel, olive, cream
- Colors I avoid or that do not suit me: bright orange, neon, pure black near my face
- Style words that feel like me: relaxed, polished, a bit French, nothing fussy
- Body and fit notes I am comfortable sharing: petite at 158 cm, prefer high-rise trousers and tops that skim rather than cling, sensitive to wool against skin
- Pieces I already own and like: dark indigo straight jeans, a navy blazer, two white t-shirts, a camel wool coat, white leather sneakers, a black midi skirt, a grey hoodie
- Pieces I own but never wear (and why): a red dress that feels too loud, skinny jeans that dig in, heels that hurt
- Budget for gaps: 600 EUR spread over the next 3 months
- Shopping values: prefer second-hand and durable natural fabrics, no fast fashion if possible
- Care limits: no dry cleaning if avoidable, machine wash at 30 degrees, no ironing time on weekdays

Please do the following:
1. Start with a short style read: 3 sentences on what my wardrobe should do for me, the 3 biggest friction points you see in my situation, and any assumption you are making.
2. Define my capsule palette: 2 or 3 base neutrals, 2 accent colors, and 1 optional statement color, each with where it works best (near the face, bottoms, shoes, outerwear), and a rule for mixing them.
3. Build a 30 to 40 piece capsule plan (excluding underwear, sleepwear, gym kit, and accessories under 5) in a table with columns: category, piece, color, fabric and weight, fit notes for my body notes, season (all year, warm, cold), already owned or gap, and priority (must, nice, later).
4. List the shopping gaps in priority order with a realistic price range for each, a second-hand search term to use, what to check in the fitting room or listing (fabric content, seams, length for a petite frame), and a running total that stays inside my budget. Mark which gaps can wait.
5. Give outfit formulas, not just outfits: 5 for work days, 5 for weekends, 3 for events, and 3 for bad weather. Write each as a repeatable formula (for example "knit polo + high-rise wide trousers + loafers + structured tote") and then one concrete example using my actual pieces.
6. Show a 2-week outfit calendar for my real week, with no outfit repeated exactly, and note which items get the most wear.
7. Cover care and longevity: washing and drying for each fabric in the plan, how to store knits and coats, how to remove pilling and refresh shoes, and when to repair rather than replace.
8. Say what to do with my unworn pieces: keep and restyle, alter, sell, donate, or swap, with one sentence of reasoning each.
9. Set a 90-day buy-nothing rule: what exactly it covers, the only allowed exceptions (for example broken shoes that cannot be repaired, a fit change, a one-off event with no rental option), a 48-hour pause test before any exception, and a simple weekly check-in question.
10. Finish with a one-page summary: palette, the 10 pieces doing the most work, the first 3 things to buy, and the 5 outfit formulas to remember.

Rules:
- Use my climate, routine, and budget; give prices as ranges and label them as estimates for my region.
- Keep fit advice about proportion, comfort, and fabric; never comment on weight or suggest dieting, and never say a body type "should not" wear something.
- Prefer pieces that work in at least 3 outfits; flag any piece that only works once.
- Respect my fabric sensitivities and care limits in every recommendation.
- No brand names unless I ask; describe pieces so I can find them anywhere, including second-hand.
- If something essential is missing, make a sensible assumption and say so instead of asking many questions.

---
name: dockerfile-best-practices-reviewer
description: Reviews Dockerfiles for security, image size, build cache, and runtime reliability: secrets baked into layers, running as root, unpinned base images, curl piped to a shell, ADD misuse, apt and pip caches left in layers, dependency installs that bust the cache, shell-form CMD, and missing multi-stage builds or health checks, then writes a corrected Dockerfile and .dockerignore. Use when a user shares a Dockerfile and asks "review my Dockerfile", "why is my image so big?", "is this container secure?", or "why does every build reinstall dependencies?". Includes a tested stdlib Python linter.
---

# Dockerfile Best Practices Reviewer

You help developers ship container images that are small, fast to rebuild, and safe to run. You read a Dockerfile the way a careful platform engineer would: you find what leaks secrets or gives away root, what makes the image heavy, and what forces slow rebuilds, and you return a corrected Dockerfile that still builds and runs the same app.

## Files in this skill

- `scripts/lint_dockerfile.py` - parses a Dockerfile (continuation lines, multi-stage builds) and reports HIGH, WARN, and INFO findings with a fix for each (Python 3 standard library only)
- `references/dockerfile-rules.md` - every rule the linter checks, why it matters, and the correct pattern
- `references/language-patterns.md` - proven multi-stage patterns for Node.js, Python, Go, and Java, plus a starter .dockerignore
- `templates/dockerfile-review.md` - the review report to return
- `examples/example-node-api-review.md` - a worked review of a Node.js API Dockerfile

## Workflow

### 1. Collect the facts
Ask, or assume and say so:
- The Dockerfile, and the .dockerignore if there is one.
- Language and framework, how the app is built and started, and the port.
- Where it runs (Kubernetes, ECS, a VM with Docker Compose, a laptop) and whether that platform already has health checks.
- Constraints: required base images (company registry, distroless, Alpine or Debian), native dependencies, and whether the build uses BuildKit.

### 2. Run the linter
```bash
python3 scripts/lint_dockerfile.py Dockerfile
python3 scripts/lint_dockerfile.py services/*/Dockerfile --fail-on warn    # stricter, for CI
python3 scripts/lint_dockerfile.py - --json < Dockerfile
```
The linter is a fast first pass based on patterns, not a full build. Read the whole Dockerfile yourself as well: it cannot know whether a package is really needed, whether a file copied in contains secrets, or whether the app writes to a path that a non-root user cannot access. If you cannot run the script, apply `references/dockerfile-rules.md` by hand.

### 3. Fix in this order
1. Security (HIGH): remove literal secrets from ENV, ARG, and RUN and use BuildKit secret mounts or runtime configuration instead; tell the user to rotate any secret that was ever committed or pushed in an image. Add a non-root USER. Replace curl-pipe-shell and chmod 777.
2. Reproducibility: pin base images to a version tag (digest for high-assurance builds) and use lockfile installs (npm ci, pip with a requirements lock, go mod download).
3. Build cache: copy dependency manifests first, install, then copy the source. Combine update and install in one RUN.
4. Size: multi-stage build, slim or distroless runtime base, no recommended packages, clean package caches in the same layer, a good .dockerignore.
5. Runtime: exec-form CMD or ENTRYPOINT, one process per container, a HEALTHCHECK if the platform has no probe, sensible WORKDIR and file ownership.
Rerun the linter on the corrected file until there are no HIGH findings and every WARN is fixed or explained.

### 4. Deliver
Fill in `templates/dockerfile-review.md`: summary, findings table, the corrected Dockerfile with short comments, a .dockerignore, how to build and test it, and an estimate of the size and rebuild-time impact. Use patterns from `references/language-patterns.md` and follow the style of `examples/example-node-api-review.md`.

## Rules
- Keep the app's behavior: same start command, port, environment variables, and files at runtime, unless the user agrees to change them.
- Never print or repeat a real secret found in the file; refer to it by name and tell the user to rotate it.
- Do not claim exact image sizes without a build; give ranges and say how to measure (`docker image ls`, `docker history`).
- Prefer official, maintained base images; mention the trade-offs of Alpine (musl) versus Debian slim versus distroless for the user's language.
- Explain each change in one line so the user learns the rule, not just the fix.
FILE:references/dockerfile-rules.md
# Dockerfile rules checked by the linter

Each rule: what is detected, why it matters, and the pattern to use instead.

## HIGH (security)

### secret-in-env / secret-in-run
Detected: ENV or ARG with a name like PASSWORD, SECRET, TOKEN, API_KEY, ACCESS_KEY, PRIVATE_KEY, CREDENTIALS and a literal value; `--password=...` or `user:pass@` URLs in RUN; ARG names that look like secrets (WARN).
Why: every ENV value and build arg is stored in the image config and history (`docker history --no-trunc`). Anyone who can pull the image can read it. Deleting it in a later layer does not remove it.
Use instead:
```dockerfile
# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN="$(cat /run/secrets/npm_token)" npm ci
```
Build with `docker build --secret id=npm_token,src=$HOME/.npm_token .`. Pass runtime secrets as environment variables from the platform or a secrets manager. Rotate any secret that was ever in an image.

### root-user
Detected: no USER in the final stage, or USER root / 0.
Why: a process that escapes the app as root inside the container has far more power over the host and other containers.
Use instead: create a user and switch before CMD; many official images already include one (`node`, `nobody`).
```dockerfile
RUN groupadd -r app && useradd -r -g app -u 10001 app
COPY --chown=app:app . /app
USER app
```

### curl-pipe-shell
Detected: `curl ... | sh` or `wget ... | bash`.
Why: runs whatever the server returns, with no integrity check; a compromised or changed script ends up in every build.
Use instead: download, verify a checksum, then run.
```dockerfile
RUN curl -fsSLo /tmp/install.sh https://example.com/install.sh \
    && echo "<sha256>  /tmp/install.sh" | sha256sum -c - \
    && sh /tmp/install.sh && rm /tmp/install.sh
```

### chmod-777
Detected: `chmod 777` or `chmod -R 777`.
Why: any user or process in the container can modify the files, including app code.
Use instead: `COPY --chown=app:app` and `chmod 755` for executables, `644` for files.

## WARN

| Rule | Detected | Why | Fix |
|---|---|---|---|
| unpinned-base | FROM without tag or with :latest | builds change silently; hard to reproduce or roll back | `FROM node:20.11-bookworm-slim` or pin a digest `@sha256:...` |
| use-copy | ADD for local files or URLs | ADD auto-extracts archives and downloads without checksums | COPY for files; curl with checksum or `ADD --checksum=` for URLs; ADD is fine for local tar archives you want extracted |
| update-alone | `apt-get update` (or apk/yum) without install in the same RUN | the cached update layer gets reused with a newer install line, so packages come from a stale index | `RUN apt-get update && apt-get install -y ...` |
| cache-bust | dependency install after `COPY . .` | any source change invalidates the install layer, so every build reinstalls everything | copy manifests first, install, then copy the source |
| sudo | sudo in RUN | not needed (build runs as root until USER), adds a setuid binary | run the step before USER |
| ssh-port | EXPOSE 22 | containers should not run SSH daemons | `docker exec`, `kubectl exec` |
| multiple-cmd | more than one CMD or ENTRYPOINT in a stage | only the last one counts; usually a mistake | keep one |

## INFO

| Rule | Fix |
|---|---|
| apt-recommends | `apt-get install -y --no-install-recommends ...` |
| apt-lists | end the same RUN with `&& rm -rf /var/lib/apt/lists/*` |
| apk-cache | `apk add --no-cache ...` |
| pip-cache | `pip install --no-cache-dir ...` or a BuildKit cache mount |
| npm-ci | `npm ci --omit=dev` uses the lockfile exactly |
| shell-form | `CMD ["node", "server.js"]` so the app is PID 1 and receives SIGTERM for graceful shutdown |
| cd-in-run | `WORKDIR /app` |
| no-healthcheck | `HEALTHCHECK CMD curl -fsS http://localhost:3000/health || exit 1` if the platform has no probe; Kubernetes ignores HEALTHCHECK and uses its own probes |
| single-stage | build in a builder stage; copy only the output into a slim runtime stage |
| many-layers | combine related RUN steps; fewer, purposeful layers |
| dockerignore | exclude `.git`, `node_modules`, `.env*`, build output, logs, and local secrets |

## What the linter cannot see
- Whether copied files contain secrets (check .dockerignore and the repo).
- Vulnerable packages in the base image or dependencies: suggest an image scanner in CI.
- Whether the non-root user can write where the app writes (logs, uploads, caches).
- Architecture issues (arm64 vs amd64), native modules, and Alpine musl compatibility.
FILE:references/language-patterns.md
# Multi-stage patterns by language

Adapt versions to the project. All examples run as a non-root user, use exec-form CMD, and keep build tools out of the runtime image.

## Node.js (npm)
```dockerfile
# syntax=docker/dockerfile:1
FROM node:20.11-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:20.11-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20.11-bookworm-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]
```
Skip the build stage if there is no compile step. Use `node:<version>-alpine` only if native modules work with musl.

## Python (pip)
```dockerfile
FROM python:3.12-slim AS build
WORKDIR /app
RUN python -m venv /venv
ENV PATH="/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM python:3.12-slim
ENV PATH="/venv/bin:$PATH" PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app
COPY --from=build /venv /venv
RUN useradd -r -u 10001 app
COPY --chown=app:app . .
USER app
EXPOSE 8000
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]
```
If packages need compilers (psycopg2, numpy from source), install `build-essential` only in the build stage.

## Go
```dockerfile
FROM golang:1.22 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
USER nonroot
ENTRYPOINT ["/app"]
```
A static Go binary on distroless or scratch gives images of a few MB to tens of MB.

## Java (Maven)
```dockerfile
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /src
COPY pom.xml .
RUN mvn -q dependency:go-offline
COPY src ./src
RUN mvn -q package -DskipTests

FROM eclipse-temurin:21-jre
RUN useradd -r -u 10001 app
WORKDIR /app
COPY --from=build --chown=app:app /src/target/app.jar app.jar
USER app
EXPOSE 8080
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "app.jar"]
```

## Starter .dockerignore
```
.git
.gitignore
.dockerignore
Dockerfile*
node_modules
dist
build
target
__pycache__
*.pyc
.venv
.env
.env.*
*.log
coverage
.idea
.vscode
secrets/
*.pem
*.key
```

## Measuring the result
- `docker build -t app:review .` then `docker image ls app:review` for size.
- `docker history app:review` to see which layers are large.
- Change one source file and rebuild: the dependency install step should say CACHED.
FILE:templates/dockerfile-review.md
# Dockerfile review: service_name

**App:** language_and_framework, started with start_command, port port
**Runs on:** platform
**Linter:** HIGH high / WARN warn / INFO info before; HIGH 0 / WARN warn_after / INFO info_after after

## Summary

Two or three sentences: the biggest security problem, the biggest size or speed problem, and the expected improvement.

## Findings

| # | Level | Line | Problem | Fix |
|---|---|---|---|---|
| 1 | HIGH | | | |

## Action needed outside the Dockerfile

- Rotate: (names of any secrets that were in the file or image, never their values)
- Platform: health probes, read-only filesystem, resource limits

## Corrected Dockerfile

```dockerfile
(full corrected Dockerfile with one-line comments on changed parts)
```

## .dockerignore

```
(entries)
```

## Build and verify

```bash
docker build -t image:review .
docker run --rm -p port:port image:review
docker image ls image:review
python3 scripts/lint_dockerfile.py Dockerfile
```

## Expected impact (estimate)

- Image size: from about ... to about ...
- Rebuild after a source change: dependency layer cached
- Security: non-root, no secrets in layers, pinned base
FILE:examples/example-node-api-review.md
# Example: review of a Node.js API Dockerfile

## User request

"Our orders API image is 1.2 GB and every build reinstalls all npm packages, even when I change one line. Can you review the Dockerfile? It runs on Kubernetes, Express app, `node server.js`, port 3000. No native modules as far as I know."

## Input Dockerfile

```dockerfile
FROM node
ENV NODE_ENV=production
ENV DB_PASSWORD=supersecret123
RUN apt-get update
RUN apt-get install -y curl git build-essential
WORKDIR /app
COPY . .
RUN npm install
RUN curl -fsSL https://example.com/install-agent.sh | bash
RUN chmod -R 777 /app
ADD config.json /app/config.json
EXPOSE 3000 22
CMD node server.js
```

## Linter run

```
$ python3 scripts/lint_dockerfile.py Dockerfile
Dockerfile: 1 stage(s): node
  HIGH 4  WARN 5  INFO 7
  HIGH line 1   root-user       the final image runs as root
  HIGH line 3   secret-in-env   ENV DB_PASSWORD contains a literal secret; it is stored in the image layers and history
  HIGH line 9   curl-pipe-shell downloads a script and pipes it straight into a shell
  HIGH line 10  chmod-777       chmod 777 makes files writable by every user
  WARN line 1   unpinned-base   base image 'node' has no tag, so it means :latest and changes without notice
  WARN line 4   update-alone    'apt-get update' runs in its own layer; a later install may use a stale cached index
  WARN line 8   cache-bust      dependencies are installed after 'COPY . .' (line 7), so any source change reinstalls them
  WARN line 11  use-copy        ADD is used for local files; it also auto-extracts archives and fetches URLs
  WARN line 12  ssh-port        port 22 (SSH) is exposed; containers should not run an SSH server
  INFO line 1   no-healthcheck  no HEALTHCHECK in the final stage
  INFO line 1   single-stage    build tools are installed in the only stage, so they ship in the final image
  INFO line 5   apt-recommends  apt installs recommended packages too
  INFO line 5   apt-lists       apt package lists are left in the layer (tens of MB)
  INFO line 7   dockerignore    COPY of the whole build context
  INFO line 8   npm-ci          npm install can change the lockfile and versions
  INFO line 13  shell-form      shell-form CMD runs under /bin/sh -c, so the app is not PID 1 and may miss SIGTERM
```

## Review (filled template, shortened)

**Linter:** HIGH 4 / WARN 5 / INFO 7 before; HIGH 0 / WARN 0 / INFO 0 after

**Summary:** The image ships a database password in its layers and runs as root, and it pipes a remote script into bash. It is large because it uses the full `node` image with compilers and git, and slow because `COPY . .` comes before `npm install`. The corrected two-stage Dockerfile removes the secret, runs as the built-in `node` user, and caches dependencies; expect roughly 200 to 300 MB instead of 1.2 GB (measure with `docker image ls`).

| # | Level | Line | Problem | Fix |
|---|---|---|---|---|
| 1 | HIGH | 3 | DB_PASSWORD literal in ENV, visible in `docker history` | removed; inject from a Kubernetes Secret at runtime |
| 2 | HIGH | - | runs as root | `USER node` (built into the official image) |
| 3 | HIGH | 9 | remote install script piped into bash | removed: the agent now runs as a Kubernetes sidecar; if it must stay, download, verify the checksum, then run |
| 4 | HIGH | 10 | chmod -R 777 /app | `COPY --chown=node:node` instead |
| 5 | WARN | 1 | untagged `node` base | `node:20.11-bookworm-slim` |
| 6 | WARN | 4 | apt-get update in its own layer | combined with install and list cleanup |
| 7 | WARN | 8 | npm install after `COPY . .` | manifests first, `npm ci --omit=dev` in a deps stage |
| 8 | WARN | 11 | ADD for a local file | COPY |
| 9 | WARN | 12 | EXPOSE 22 | removed; use `kubectl exec` |
| 10 | INFO | 5, 13 | build tools and git in the runtime image, shell-form CMD | dropped (no native modules), exec-form CMD |

**Action needed outside the Dockerfile:** rotate DB_PASSWORD now (it is in every image pushed so far), and add it to the Deployment from a Kubernetes Secret. Kubernetes ignores HEALTHCHECK, so also add a readiness and liveness probe on /health; the HEALTHCHECK below helps local Docker and Compose.

## Corrected Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
FROM node:20.11-bookworm-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:20.11-bookworm-slim
ENV NODE_ENV=production
WORKDIR /app
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*
COPY --from=deps /app/node_modules ./node_modules
COPY --chown=node:node src/ ./src/
COPY --chown=node:node config.json ./
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS http://localhost:3000/health || exit 1
CMD ["node", "src/server.js"]
```

## .dockerignore

```
.git
node_modules
.env
.env.*
*.log
coverage
Dockerfile*
```

## Verify

```
$ python3 scripts/lint_dockerfile.py Dockerfile
Dockerfile: 2 stage(s): node:20.11-bookworm-slim AS deps, node:20.11-bookworm-slim
  HIGH 0  WARN 0  INFO 0
  no problems found
```

Note: the source now lives in `src/`, so the start command became `node src/server.js`; if your entry file is elsewhere, keep your original path. If a dependency turns out to need compilers, install `build-essential` and `python3` in the deps stage only.
FILE:scripts/lint_dockerfile.py
#!/usr/bin/env python3
"""Review a Dockerfile for security, image size, build cache, and reliability problems.

Usage:
  python3 lint_dockerfile.py Dockerfile [more Dockerfiles] [--json] [--fail-on high|warn|info]
  python3 lint_dockerfile.py - < Dockerfile

Checks (rule ids in brackets):
  HIGH  secrets in ENV/ARG or in RUN (secret-in-env, secret-in-run), final stage runs as root
        (root-user), pipe from curl/wget to a shell (curl-pipe-shell), chmod 777 (chmod-777)
  WARN  untagged or :latest base image (unpinned-base), ADD for local files or URLs (use-copy),
        apt/apk/yum update without install in the same RUN (update-alone), COPY of the whole
        context before installing dependencies (cache-bust), sudo (sudo), EXPOSE 22 (ssh-port),
        more than one CMD or ENTRYPOINT in a stage (multiple-cmd)
  INFO  apt-get without --no-install-recommends or without cleaning lists, pip without
        --no-cache-dir, npm install instead of npm ci, shell-form CMD/ENTRYPOINT, cd in RUN
        instead of WORKDIR, no HEALTHCHECK, single-stage build with build tools, many RUN layers,
        COPY of the whole context (check .dockerignore)
Exit codes: 0 ok, 1 findings at or above --fail-on (default high), 2 usage or read error.
Python 3 standard library only.
"""
import json
import re
import shlex
import sys

LEVELS = {"info": 0, "warn": 1, "high": 2}
SECRET_KEY = re.compile(r"(PASSWORD|PASSWD|SECRET|TOKEN|API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|CREDENTIALS?)", re.I)
BUILD_TOOLS = re.compile(r"\b(build-essential|gcc|g\+\+|make|cmake|maven|gradle|golang|rustc|cargo|npm run build|go build|mvn )", re.I)


def logical_lines(text):
    """Join continuation lines; return list of (line_no, instruction, args). Skips comments and parser directives."""
    out, buf, start = [], "", None
    escape = "\"
    for i, raw in enumerate(text.replace("
", "
").split("
"), 1):
        m = re.match(r"^#\s*escape\s*=\s*(\S)", raw)
        if m and not out and not buf:
            escape = m.group(1)
            continue
        s = raw.strip()
        if not buf and (not s or s.startswith("#")):
            continue
        if buf and s.startswith("#"):
            continue
        if start is None:
            start = i
        if s.endswith(escape):
            buf += s[:-1] + " "
            continue
        buf += s
        parts = buf.split(None, 1)
        out.append((start, parts[0].upper(), parts[1] if len(parts) > 1 else ""))
        buf, start = "", None
    if buf:
        parts = buf.split(None, 1)
        out.append((start, parts[0].upper(), parts[1] if len(parts) > 1 else ""))
    return out


def review(text):
    lines = logical_lines(text)
    findings = []

    def add(level, rule, line, msg, fix):
        findings.append({"level": level, "rule": rule, "line": line, "message": msg, "fix": fix})

    if not any(ins == "FROM" for _, ins, _ in lines):
        raise ValueError("no FROM instruction found (is this a Dockerfile?)")
    stages, cur = [], None
    for ln, ins, args in lines:
        if ins == "FROM":
            m = re.match(r"(?:--platform=\S+\s+)?(\S+)(?:\s+AS\s+(\S+))?", args, re.I)
            cur = {"line": ln, "image": m.group(1) if m else args, "name": m.group(2) if m else None, "ins": []}
            stages.append(cur)
        elif cur is not None:
            cur["ins"].append((ln, ins, args))
    names = {s["name"].lower() for s in stages if s["name"]}
    arg_names = {a.split("=")[0].strip() for _, i, a in lines if i == "ARG"}

    for s in stages:
        img = s["image"]
        if img.lower() in names or img == "scratch" or img.startswith("$"):
            pass
        elif "@sha256:" in img:
            pass
        elif ":" not in img.split("/")[-1]:
            add("warn", "unpinned-base", s["line"], f"base image '{img}' has no tag, so it means :latest and changes without notice",
                f"pin a version, e.g. {img}:<version>-slim, or a digest")
        elif img.endswith(":latest"):
            add("warn", "unpinned-base", s["line"], f"base image '{img}' uses :latest", "pin a specific version tag or digest")

    final = stages[-1]
    run_count = 0
    for idx, s in enumerate(stages):
        cmds = [x for x in s["ins"] if x[1] in ("CMD", "ENTRYPOINT")]
        for kind in ("CMD", "ENTRYPOINT"):
            k = [x for x in cmds if x[1] == kind]
            if len(k) > 1:
                add("warn", "multiple-cmd", k[-1][0], f"{len(k)} {kind} instructions in one stage; only the last one counts",
                    f"keep a single {kind}")
        copied_all = None
        for ln, ins, args in s["ins"]:
            low = args.lower()
            if ins in ("ENV", "ARG"):
                pairs = re.findall(r"([A-Za-z_][A-Za-z0-9_]*)(?:(?:=|\s+)(\"[^\"]*\"|'[^']*'|[^\s=]\S*))?", args) if ins == "ARG" or "=" in args else [tuple((args.split(None, 1) + [""])[:2])]
                for key, val in pairs:
                    if SECRET_KEY.search(key) and val and not val.startswith("$") and val.strip("\"'"):
                        add("high", "secret-in-env", ln, f"{ins} {key} contains a literal secret; it is stored in the image layers and history",
                            "pass secrets at build time with RUN --mount=type=secret, or at run time via environment or a secrets manager")
                if ins == "ARG" and any(SECRET_KEY.search(k) for k, _ in pairs) and not any(v for k, v in pairs if SECRET_KEY.search(k)):
                    add("warn", "secret-in-env", ln, f"ARG {pairs[0][0]} looks like a secret; build args are visible in image history",
                        "use RUN --mount=type=secret instead of a build arg")
            if ins == "RUN":
                run_count += 1
                if re.search(r"(curl|wget)\b[^|;&]*\|\s*(sudo\s+)?(ba|z|da)?sh\b", low):
                    add("high", "curl-pipe-shell", ln, "downloads a script and pipes it straight into a shell",
                        "download to a file, verify a checksum or signature, then run it")
                if re.search(r"chmod\s+(-r\s+)?0?777\b", low):
                    add("high", "chmod-777", ln, "chmod 777 makes files writable by every user", "grant only the permissions needed, e.g. chmod 755 or chown to the app user")
                if re.search(r"(--password[= ]\S+|://[^/\s:@]+:[^@\s$]+@)", args) or re.search(r"\b(token|api[_-]?key)=\w{8,}", low):
                    add("high", "secret-in-run", ln, "a password, token, or credentials URL appears in a RUN command and stays in the image history",
                        "use RUN --mount=type=secret or fetch credentials at run time")
                if re.search(r"\bsudo\b", low):
                    add("warn", "sudo", ln, "sudo inside a Dockerfile is unnecessary and widens the attack surface", "run the step before switching USER, without sudo")
                for upd, inst in (("apt-get update", "apt-get install"), ("apt update", "apt install"), ("apk update", "apk add"), ("yum update", "yum install")):
                    if upd in low and inst not in low:
                        add("warn", "update-alone", ln, f"'{upd}' runs in its own layer; a later install may use a stale cached index",
                            f"combine: RUN {upd} && {inst} ... in one RUN")
                if "apt-get install" in low or "apt install" in low:
                    if "--no-install-recommends" not in low:
                        add("info", "apt-recommends", ln, "apt installs recommended packages too", "add --no-install-recommends")
                    if "/var/lib/apt/lists" not in low:
                        add("info", "apt-lists", ln, "apt package lists are left in the layer (tens of MB)", "end the same RUN with && rm -rf /var/lib/apt/lists/*")
                if "apk add" in low and "--no-cache" not in low:
                    add("info", "apk-cache", ln, "apk cache is kept in the layer", "use apk add --no-cache")
                if re.search(r"\bpip3?\s+install\b", low) and "--no-cache-dir" not in low and "--mount=type=cache" not in low:
                    add("info", "pip-cache", ln, "pip keeps its download cache in the layer", "add --no-cache-dir (or use a cache mount)")
                if any(re.fullmatch(r"\s*npm\s+(install|i)(\s+--?(?!g\b|global\b)[\w-]+(=\S+)?)*\s*", seg) for seg in re.split(r"&&|;|\|\|", low)):
                    add("info", "npm-ci", ln, "npm install can change the lockfile and versions", "use npm ci (with --omit=dev for production)")
                if re.match(r"cd\s+\S+\s*&&", low) or re.search(r"&&\s*cd\s+/", low):
                    add("info", "cd-in-run", ln, "cd in RUN only affects that one command", "use WORKDIR /path")
                if copied_all and re.search(r"\b(npm (ci|install)|pip3? install -r|poetry install|bundle install|go mod download|composer install|yarn install)\b", low):
                    add("warn", "cache-bust", ln, f"dependencies are installed after 'COPY {copied_all[1]}' (line {copied_all[0]}), so any source change reinstalls them",
                        "copy only the manifest and lockfile first (e.g. COPY package*.json ./), install, then COPY the rest")
                    copied_all = None
            if ins == "ADD":
                src = args.split()[0] if args.split() else ""
                if re.match(r"https?://", src):
                    add("warn", "use-copy", ln, "ADD with a URL downloads without checksum verification and leaves the file in a layer",
                        "use RUN curl -fsSL ... with a checksum check, or ADD --checksum=sha256:...")
                elif not re.search(r"\.(tar|tar\.gz|tgz|tar\.xz|tar\.bz2)$", src):
                    add("warn", "use-copy", ln, "ADD is used for local files; it also auto-extracts archives and fetches URLs", "use COPY for plain files")
            if ins == "COPY" and not args.startswith("--from"):
                parts = [p for p in args.split() if not p.startswith("--")]
                if parts and parts[0] in (".", "./", "*"):
                    copied_all = (ln, " ".join(parts))
                    add("info", "dockerignore", ln, "COPY of the whole build context", "make sure .dockerignore excludes .git, node_modules, .env, build output, and secrets")
            if ins == "EXPOSE" and re.search(r"\b22\b", args):
                add("warn", "ssh-port", ln, "port 22 (SSH) is exposed; containers should not run an SSH server", "use docker exec / kubectl exec for access")
            if ins in ("CMD", "ENTRYPOINT") and not args.strip().startswith("["):
                add("info", "shell-form", ln, f"shell-form {ins} runs under /bin/sh -c, so the app is not PID 1 and may miss SIGTERM",
                    f'use exec form: {ins} ["executable", "arg"]')

    users = [(ln, a.strip()) for ln, i, a in final["ins"] if i == "USER"]
    if not users or users[-1][1].split(":")[0] in ("root", "0"):
        where = users[-1][0] if users else final["line"]
        add("high", "root-user", where, "the final image runs as root",
            "create an unprivileged user (e.g. RUN useradd -r -u 10001 app) and add USER app before CMD")
    if not any(i == "HEALTHCHECK" for _, i, _ in final["ins"]):
        add("info", "no-healthcheck", final["line"], "no HEALTHCHECK in the final stage", "add HEALTHCHECK CMD ... if no orchestrator health probe is configured")
    if len(stages) == 1 and any(BUILD_TOOLS.search(a) for _, i, a in final["ins"] if i == "RUN"):
        add("info", "single-stage", final["line"], "build tools are installed in the only stage, so they ship in the final image",
            "use a multi-stage build: compile in a builder stage, COPY --from=builder only the output")
    if run_count > 10:
        add("info", "many-layers", final["line"], f"{run_count} RUN instructions; related steps can be combined", "group related commands with && in fewer RUN steps")
    return {"stages": [{"line": s["line"], "image": s["image"], "name": s["name"]} for s in stages], "findings": findings}


def main(argv):
    as_json, fail_on, files = False, "high", []
    it = iter(argv)
    for a in it:
        if a == "--json":
            as_json = True
        elif a == "--fail-on":
            fail_on = next(it, "").lower()
            if fail_on not in LEVELS:
                print("error: --fail-on must be high, warn, or info", file=sys.stderr)
                return 2
        elif a in ("-h", "--help"):
            print(__doc__)
            return 0
        elif a.startswith("--"):
            print(f"error: unknown option {a}", file=sys.stderr)
            return 2
        else:
            files.append(a)
    if not files:
        print("error: give a Dockerfile path, or - for stdin", file=sys.stderr)
        return 2
    reports, worst = [], -1
    for f in files:
        try:
            text = sys.stdin.read() if f == "-" else open(f, encoding="utf-8").read()
            r = review(text)
        except (OSError, UnicodeDecodeError, ValueError) as e:
            print(f"error: {f}: {e}", file=sys.stderr)
            return 2
        r["file"] = f
        r["findings"].sort(key=lambda x: (-LEVELS[x["level"]], x["line"]))
        for x in r["findings"]:
            worst = max(worst, LEVELS[x["level"]])
        reports.append(r)
    if as_json:
        print(json.dumps(reports, indent=2))
    else:
        for r in reports:
            c = {lv: sum(1 for x in r["findings"] if x["level"] == lv) for lv in LEVELS}
            st = ", ".join(f"{s['image']}" + (f" AS {s['name']}" if s["name"] else "") for s in r["stages"])
            print(f"{r['file']}: {len(r['stages'])} stage(s): {st}")
            print(f"  HIGH {c['high']}  WARN {c['warn']}  INFO {c['info']}")
            for x in r["findings"]:
                print(f"  {x['level'].upper():<4} line {x['line']:<3} {x['rule']:<15} {x['message']}")
                print(f"       fix: {x['fix']}")
            if not r["findings"]:
                print("  no problems found")
    return 1 if worst >= LEVELS[fail_on] else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: loan-amortization-planner
description: Builds fixed-rate loan and mortgage amortization schedules, shows how much of each payment goes to interest, and compares payoff strategies such as extra monthly payments, one-off lump sums, a higher fixed payment, or a shorter term, with interest saved, months saved, payoff date, and an APR estimate when fees apply. Use when a user asks "how much interest will I pay?", "should I overpay my mortgage?", "what if I pay 200 more a month?", or wants a payoff plan for a car, student, personal, or home loan. Includes a tested stdlib Python calculator.
---

# Loan Amortization Planner

You help people understand what a loan really costs and how to pay it off faster in a way that fits their budget. You run the numbers precisely, explain them in plain language, compare realistic options side by side, and point out the trade-offs (emergency savings, other debts, prepayment rules) before anyone sends extra money to a lender.

## Files in this skill

- `scripts/amortize.py` - monthly amortization for fixed-rate loans with extra monthly payments, lump sums, a fixed payment, fees and an APR estimate, a yearly table, and a CSV schedule (Python 3 standard library only)
- `references/amortization-basics.md` - how amortization works, the formulas, and the terms people confuse (rate vs APR, term vs payoff date)
- `references/prepayment-decision-guide.md` - when overpaying makes sense, what to check in the loan contract, and the order of priorities
- `templates/loan-plan.md` - the report to return
- `examples/example-mortgage-overpayment.md` - a worked comparison of three overpayment strategies on a mortgage

## Workflow

### 1. Collect the facts
Ask, or assume and say so:
- Amount still owed (or amount to borrow), interest rate, remaining term, and the current monthly payment if known.
- Fixed or variable rate, and when a fixed period ends.
- Fees: arrangement or origination fees, and any prepayment penalty or yearly overpayment limit.
- What the user can afford: an extra amount per month, an expected bonus or one-off sum, and their emergency savings and other debts.
- The goal: lowest total interest, being debt-free by a date, or lowest monthly payment.

### 2. Run the baseline
```bash
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --start 2026-12
python3 scripts/amortize.py --principal 18500 --rate 7.9 --months 48 --fee 400   # car loan with a fee: APR estimate
```
Check that the computed payment matches the lender's statement within a few cents. If it does not, the loan probably has a different day count, fees in the balance, or insurance in the payment: ask, or use `--payment` with the real amount.

### 3. Run the scenarios
```bash
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --extra 200
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --lump 12:10000 --lump 24:10000
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 30 --payment 2000 --yearly
python3 scripts/amortize.py --principal 300000 --rate 4.5 --years 20                # shorter term
python3 scripts/amortize.py ... --schedule plan.csv --json
```
Compare 2 to 4 options that the user can really afford. For each, record the monthly outlay, payoff date, total interest, interest saved, and months saved. If you cannot run the script, use the formulas in `references/amortization-basics.md` and say the numbers are approximate.

### 4. Check the decision, not just the math
Go through `references/prepayment-decision-guide.md`: emergency fund first, higher-rate debts first, prepayment penalties and limits, tax effects to check locally, and the after-tax return of the alternative (saving or investing). Never present overpaying as always right.

### 5. Deliver
Fill in `templates/loan-plan.md`: the loan in one line, the baseline, a comparison table of scenarios, a recommendation with reasons, what to ask the lender, and next steps. Follow the style of `examples/example-mortgage-overpayment.md`.

## Rules
- Show every number with its currency and round money to cents; label estimates as estimates.
- The calculator assumes a fixed rate, monthly payments, and extra payments applied to principal straight away with the payment unchanged (the term shortens). Say so, and flag variable rates or lenders that recalculate the payment instead.
- Do not give personal investment or tax advice; explain the trade-off and tell the user what to check with the lender or a licensed adviser.
- If a payment does not even cover the interest, say so clearly and stop: the balance would grow.
- Keep the explanation short and concrete: "every 100 of extra saves about 120 of interest" beats a paragraph of theory.
FILE:references/amortization-basics.md
# Amortization basics

## How a fixed-rate loan is paid off

Each month the lender charges interest on the balance still owed. Your payment first covers that interest; the rest reduces the balance (principal). Because the balance falls, the interest part shrinks every month and the principal part grows, while the payment stays the same. Early payments are mostly interest; late payments are mostly principal.

## Formulas

- Monthly rate: r = annual rate / 12 (for example 4.5% -> 0.00375).
- Payment for a loan P over n months: M = P * r / (1 - (1 + r)^-n). With r = 0: M = P / n.
- Interest this month: balance * r. Principal this month: M - interest.
- Total interest: sum of the interest parts, or approximately M * n - P.
- Months to pay off with payment M: n = -ln(1 - P * r / M) / ln(1 + r). If P * r >= M the loan never ends.

Quick checks: 200,000 at 6% for 30 years -> 1,199.10 per month. 300,000 at 4.5% for 30 years -> 1,520.06 per month.

## Why extra payments save so much

An extra payment reduces the balance immediately, so every later month charges interest on a smaller amount. The saving is roughly the extra amount times the interest it would have carried for the rest of the loan. That is why money paid early in the loan saves more than the same money paid late.

## Terms people confuse

| Term | Meaning |
|---|---|
| Nominal rate | The yearly rate in the contract, used for the monthly interest. |
| APR | Annual percentage rate including fees; compares offers. A loan with a lower rate but high fees can have a higher APR. |
| Term | The planned length (e.g. 30 years). |
| Payoff date | When the balance actually reaches zero; earlier with extra payments. |
| Reduce term vs reduce payment | After an overpayment, some lenders keep the payment and shorten the term (saves more interest), others recalculate a lower payment. Ask which. |
| Principal | The amount still owed, not counting future interest. |
| Amortization schedule | The month-by-month table of payment, interest, principal, and balance. |

## Rounding and small differences

Lenders round to cents each month and may use daily interest (actual days / 365) instead of rate / 12. Results can differ by a few cents per month and a few units in total interest. The last payment usually absorbs the rounding difference.

## Limits of a fixed-rate calculator

- Variable or tracker rates: run scenarios at the current rate and at +1 and +2 percentage points.
- Interest-only periods, balloon payments, payment holidays: model them separately or by hand.
- Insurance, escrow, or account fees inside the monthly payment are not interest; remove them before comparing.
FILE:references/prepayment-decision-guide.md
# Should I pay off my loan faster? A decision guide

Overpaying a loan gives a guaranteed, risk-free "return" equal to the loan's interest rate. That is good, but it is not always the best use of spare money. Work through these steps in order.

## 1. Safety first
- Emergency fund: keep about 3 to 6 months of essential costs in easy-access savings before overpaying. Money sent to a lender is hard to get back.
- Stable income: if a job change, parental leave, or a big expense is coming, build cash first.

## 2. Pay the most expensive debt first
Rank debts by interest rate (avalanche method): credit cards and overdrafts, then personal and car loans, then student loans and mortgages. Overpay the highest rate first. If motivation is the problem, paying the smallest balance first (snowball) can be fine, but say what it costs.

## 3. Read the contract
- Prepayment penalty or early repayment charge (often a percent of the amount overpaid, mostly during a fixed-rate period).
- Yearly overpayment allowance (for example 10 percent of the balance per year without a fee).
- Does an overpayment reduce the term or the payment? Can you choose?
- Minimum overpayment amounts and how to make one (online, by phone, written instruction).

## 4. Compare with the alternative
- Employer retirement matching is usually better than any overpayment: take the full match first.
- Compare the loan rate with the after-tax, after-fee return you could get on savings. A 2% mortgage versus a 4% savings account: saving wins on paper. A 7% car loan versus a 3% savings account: overpaying wins.
- Investing may beat a low-rate loan over long periods but carries risk; the overpayment return is certain.
- Tax: in some countries mortgage interest is tax-deductible, which lowers the effective rate. Check locally; do not assume.

## 5. Pick a strategy
| Strategy | Good when |
|---|---|
| Fixed extra per month | Steady income; builds a habit; saves the most for the same total if started early. |
| Lump sums (bonus, tax refund) | Irregular income; keeps flexibility during the year. |
| Higher fixed payment | Wants a clear debt-free date. |
| Refinance to a shorter term | A lower rate is available and the higher payment is affordable; compare fees. |
| Keep cash, overpay later | Fixed period ending soon (overpay without penalty after), or emergency fund not full. |

## 6. Review
Re-run the numbers once a year, when the rate changes, or when income changes. Remind the user that overpaying can always be paused; a higher contractual payment usually cannot.
FILE:templates/loan-plan.md
# Loan plan: loan_name

**Loan:** balance at rate% (fixed_or_variable), remaining_term left, payment payment per month, first payment in this plan start_month
**Fees and rules:** fees; prepayment limit or penalty: prepayment_rules
**Goal:** goal
**Budget for extra payments:** extra_budget

## Baseline

- Monthly payment: 
- Total interest from now: 
- Payoff date: 
- First payment split: interest ... / principal ...

## Scenarios

| Option | Monthly outlay | Payoff date | Total interest | Interest saved | Months saved |
|---|---|---|---|---|---|
| Baseline | | | | - | - |
| A: | | | | | |
| B: | | | | | |
| C: | | | | | |

## Recommendation

Option ... because:
1. 
2. 
3. 

Trade-offs to keep in mind: 

## Before you overpay

- [ ] Emergency fund covers ... months
- [ ] No higher-rate debt left (or it comes first)
- [ ] Prepayment penalty / allowance checked with the lender
- [ ] Overpayment set to reduce the term (or payment, if preferred)

## Questions for the lender

1. 
2. 

## Next steps

1. 
2. 

*Assumptions: fixed rate, monthly payments, extra payments applied to principal immediately. These are estimates, not financial advice.*
FILE:examples/example-mortgage-overpayment.md
# Example: comparing three mortgage overpayment strategies

## User request

"We have 320,000 left on our mortgage at 4.1% fixed with 25 years to go, first payment of this plan in December 2026. We could pay about 300 extra a month, or we get a 15,000 bonus each year for the next three years. A friend says we should just switch to 2,400 a month. What's best? We have 6 months of expenses saved and no other debt. The bank allows 10% overpayment per year without fees."

## Commands

```bash
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12 --extra 300
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12 --lump 12:15000 --lump 24:15000 --lump 36:15000
python3 scripts/amortize.py --principal 320000 --rate 4.1 --years 25 --start 2026-12 --payment 2400
```

Output (shortened):

```
Baseline: 1,706.80 per month, interest 192,038.38, total paid 512,038.38, paid off 2051-11 (300 payments)
Plan (+300.00/month): paid off 2046-02 (231 payments), interest 143,068.39
  Saves 48,969.99 interest and 69 months (5 y 9 m); every 100 of extra saves 70.97
Plan (lump sums 15,000.00 in payment 12, 15,000.00 in payment 24, 15,000.00 in payment 36): paid off 2046-11 (240 payments), interest 133,018.73
  Saves 59,019.65 interest and 60 months (5 y 0 m); every 100 of extra saves 131.15
Plan (fixed payment 2,400.00): paid off 2041-10 (179 payments), interest 107,805.37
  Saves 84,233.01 interest and 121 months (10 y 1 m)
```

## Loan plan (filled template, shortened)

**Loan:** 320,000.00 at 4.1% fixed, 25 years left, payment 1,706.80 per month, first payment December 2026
**Fees and rules:** overpayments up to 10% of the balance per year are free
**Goal:** pay less interest without losing flexibility

| Option | Monthly outlay | Payoff date | Total interest | Interest saved | Months saved |
|---|---|---|---|---|---|
| Baseline | 1,706.80 | 2051-11 | 192,038.38 | - | - |
| A: +300 per month | 2,006.80 | 2046-02 | 143,068.39 | 48,969.99 | 69 |
| B: 15,000 bonus in years 1 to 3 | 1,706.80 + 45,000 total | 2046-11 | 133,018.73 | 59,019.65 | 60 |
| C: fixed 2,400 per month | 2,400.00 | 2041-10 | 107,805.37 | 84,233.01 | 121 |

**Recommendation:** Option B, plus A if the budget allows. The bonuses are paid early in the loan, so each 100 overpaid saves about 131 of interest, almost twice the rate of the monthly plan (about 71 per 100, because much of that money is paid in later years). It needs no change to the monthly budget, and each 15,000 is within the free 10% allowance (32,000 in year 1). Option C saves the most because it sends about 124,000 of extra money over 15 years, but it raises the fixed outlay by 693 per month; do it only if that fits comfortably, and set it up as a voluntary overpayment rather than a new contract payment so it can be paused.

**Trade-offs:** money overpaid is hard to get back; keep the 6-month emergency fund untouched. If your savings account pays more than 4.1% after tax, saving could beat overpaying on paper; check the rate and any tax rules locally.

**Questions for the lender:**
1. Will overpayments reduce the term with the payment unchanged (assumed above), or recalculate the payment?
2. Does the 10% allowance reset per calendar year or per loan year?

*Assumptions: fixed rate for the whole term, monthly payments, overpayments applied to principal immediately. Estimates, not financial advice.*
FILE:scripts/amortize.py
#!/usr/bin/env python3
"""Fixed-rate loan amortization with extra payments and scenario comparison.

Usage:
  python3 amortize.py --principal 250000 --rate 4.2 --years 30 [options]
  python3 amortize.py --principal 18000 --rate 7.9 --months 60 --extra 150

Options:
  --principal N      amount borrowed (required)
  --rate PCT         nominal annual interest rate in percent, e.g. 4.2 (required; 0 allowed)
  --years N | --months N   term (one of them is required)
  --start YYYY-MM    month of the first payment (default: next month)
  --extra N          extra amount added to every monthly payment
  --extra-from N     payment number where --extra starts (default 1)
  --lump N:AMOUNT    one-off extra payment in payment number N (repeatable)
  --payment N        pay this fixed monthly amount instead of the computed one
  --fee N            one-off upfront fees, used for the cost and APR estimate
  --schedule FILE    write the full monthly schedule as CSV
  --yearly           print a year-by-year table
  --json             print the result as JSON

Extra payments are assumed to reduce principal immediately with no prepayment
penalty and the same monthly payment (term shortens). Rates are nominal annual,
compounded monthly (rate / 12 per month). Money is rounded to cents each month.
Exit codes: 0 ok, 2 usage or input error. Python 3 standard library only.
"""
import argparse
import csv
import datetime as dt
import json
import sys


def monthly_payment(principal, annual_rate, n):
    r = annual_rate / 100 / 12
    if r == 0:
        return principal / n
    return principal * r / (1 - (1 + r) ** -n)


def add_months(ym, k):
    y, m = ym
    m0 = m - 1 + k
    return (y + m0 // 12, m0 % 12 + 1)


def schedule(principal, annual_rate, n, payment=None, extra=0.0, extra_from=1, lumps=None):
    r = annual_rate / 100 / 12
    base = round(payment if payment else monthly_payment(principal, annual_rate, n), 2)
    lumps = lumps or {}
    bal = round(principal, 2)
    rows = []
    k = 0
    while bal > 0.005:
        k += 1
        if k > 1200:
            raise ValueError("the loan is not paid off within 100 years; the payment is too small for the interest")
        interest = round(bal * r, 2)
        if base + (extra if k >= extra_from else 0) <= interest and not lumps.get(k):
            raise ValueError(f"payment {base:.2f} does not cover the monthly interest {interest:.2f}; the balance would grow")
        sched = min(base, bal + interest)
        if payment is None and k == n:
            sched = bal + interest  # last scheduled payment absorbs the rounding difference
        ext = min(extra if k >= extra_from else 0.0, max(bal + interest - sched, 0))
        lump = min(lumps.get(k, 0.0), max(bal + interest - sched - ext, 0))
        principal_paid = round(sched + ext + lump - interest, 2)
        bal = round(bal - principal_paid, 2)
        rows.append({"n": k, "payment": round(sched, 2), "extra": round(ext + lump, 2), "interest": interest,
                     "principal": principal_paid, "balance": max(bal, 0.0)})
    return base, rows


def summarize(rows):
    return {"months": len(rows), "total_interest": round(sum(x["interest"] for x in rows), 2),
            "total_paid": round(sum(x["payment"] + x["extra"] for x in rows), 2),
            "total_extra": round(sum(x["extra"] for x in rows), 2)}


def apr_estimate(principal, fee, payment, n):
    """Annual rate that makes the payments worth principal - fee (bisection)."""
    target = principal - fee
    lo, hi = 0.0, 1.0
    for _ in range(100):
        mid = (lo + hi) / 2
        r = mid / 12
        pv = payment * n if r == 0 else payment * (1 - (1 + r) ** -n) / r
        lo, hi = (mid, hi) if pv > target else (lo, mid)
    return round(lo * 100, 3)


def fmt_ym(ym):
    return f"{ym[0]:04d}-{ym[1]:02d}"


def main(argv):
    p = argparse.ArgumentParser(add_help=True, description="Loan amortization with extra payments")
    p.add_argument("--principal", type=float, required=True)
    p.add_argument("--rate", type=float, required=True)
    g = p.add_mutually_exclusive_group(required=True)
    g.add_argument("--years", type=float)
    g.add_argument("--months", type=int)
    p.add_argument("--start")
    p.add_argument("--extra", type=float, default=0.0)
    p.add_argument("--extra-from", type=int, default=1)
    p.add_argument("--lump", action="append", default=[])
    p.add_argument("--payment", type=float)
    p.add_argument("--fee", type=float, default=0.0)
    p.add_argument("--schedule")
    p.add_argument("--yearly", action="store_true")
    p.add_argument("--json", action="store_true")
    try:
        a = p.parse_args(argv)
    except SystemExit as e:
        return 0 if e.code == 0 else 2
    try:
        n = a.months if a.months else round(a.years * 12)
        if a.principal <= 0 or n <= 0 or a.rate < 0 or a.extra < 0 or a.fee < 0:
            raise ValueError("principal and term must be positive; rate, extra, and fee cannot be negative")
        if a.rate > 100:
            raise ValueError("rate is in percent per year, e.g. 4.2 for 4.2%")
        lumps = {}
        for item in a.lump:
            num, _, amt = item.partition(":")
            try:
                if not num.isdigit():
                    raise ValueError
                value = float(amt)
            except ValueError:
                raise ValueError(f"--lump must look like 24:5000 (payment number:amount), got {item!r}") from None
            lumps[int(num)] = lumps.get(int(num), 0.0) + value
        if a.start:
            try:
                y, m = a.start.split("-")
                start = (int(y), int(m))
            except ValueError:
                raise ValueError(f"--start must look like 2026-11, got {a.start!r}") from None
            if not 1 <= start[1] <= 12:
                raise ValueError("--start month must be 01 to 12")
        else:
            t = dt.date.today()
            start = add_months((t.year, t.month), 1)
        base_pay, base_rows = schedule(a.principal, a.rate, n, payment=None)
        scenario = bool(a.extra or lumps or a.payment)
        pay, rows = schedule(a.principal, a.rate, n, payment=a.payment, extra=a.extra,
                             extra_from=a.extra_from, lumps=lumps) if scenario else (base_pay, base_rows)
    except ValueError as e:
        print(f"error: {e}", file=sys.stderr)
        return 2

    base_sum, plan_sum = summarize(base_rows), summarize(rows)
    result = {
        "inputs": {"principal": a.principal, "annual_rate_pct": a.rate, "term_months": n, "first_payment": fmt_ym(start),
                   "extra_monthly": a.extra, "extra_from_payment": a.extra_from, "lumps": lumps, "fixed_payment": a.payment, "fees": a.fee},
        "baseline": {"monthly_payment": base_pay, **base_sum, "payoff": fmt_ym(add_months(start, base_sum["months"] - 1))},
    }
    if a.fee:
        result["baseline"]["apr_estimate_pct"] = apr_estimate(a.principal, a.fee, base_pay, n)
        result["baseline"]["total_cost_incl_fees"] = round(base_sum["total_interest"] + a.fee, 2)
    if scenario:
        result["plan"] = {"monthly_payment": pay, **plan_sum, "payoff": fmt_ym(add_months(start, plan_sum["months"] - 1)),
                          "months_saved": base_sum["months"] - plan_sum["months"],
                          "interest_saved": round(base_sum["total_interest"] - plan_sum["total_interest"], 2)}
        if plan_sum["total_extra"]:
            result["plan"]["interest_saved_per_100_extra"] = round(100 * result["plan"]["interest_saved"] / plan_sum["total_extra"], 2)
    yearly = []
    for i in range(0, len(rows), 12):
        chunk = rows[i:i + 12]
        yearly.append({"year": i // 12 + 1, "paid": round(sum(x["payment"] + x["extra"] for x in chunk), 2),
                       "interest": round(sum(x["interest"] for x in chunk), 2),
                       "principal": round(sum(x["principal"] for x in chunk), 2), "end_balance": chunk[-1]["balance"]})
    result["yearly"] = yearly
    first = base_rows[0]
    result["baseline"]["first_payment_split"] = {"interest": first["interest"], "principal": first["principal"]}

    if a.schedule:
        try:
            with open(a.schedule, "w", newline="", encoding="utf-8") as f:
                w = csv.writer(f)
                w.writerow(["n", "month", "payment", "extra", "interest", "principal", "balance"])
                for x in rows:
                    w.writerow([x["n"], fmt_ym(add_months(start, x["n"] - 1)), f"{x['payment']:.2f}", f"{x['extra']:.2f}",
                                f"{x['interest']:.2f}", f"{x['principal']:.2f}", f"{x['balance']:.2f}"])
        except OSError as e:
            print(f"error: cannot write schedule {a.schedule}: {e.strerror}", file=sys.stderr)
            return 2
    if a.json:
        print(json.dumps(result, indent=2))
        return 0
    b = result["baseline"]
    print(f"Loan {a.principal:,.2f} at {a.rate}% for {n} months, first payment {fmt_ym(start)}")
    print(f"Baseline: {b['monthly_payment']:,.2f} per month, interest {b['total_interest']:,.2f}, "
          f"total paid {b['total_paid']:,.2f}, paid off {b['payoff']} ({b['months']} payments)")
    if a.fee:
        print(f"  With fees {a.fee:,.2f}: total cost of borrowing {b['total_cost_incl_fees']:,.2f}, APR about {b['apr_estimate_pct']}%")
    print(f"  First payment: {first['interest']:,.2f} interest, {first['principal']:,.2f} principal")
    if scenario:
        pl = result["plan"]
        what = []
        if a.payment:
            what.append(f"fixed payment {a.payment:,.2f}")
        if a.extra:
            what.append(f"+{a.extra:,.2f}/month" + (f" from payment {a.extra_from}" if a.extra_from > 1 else ""))
        if lumps:
            what.append("lump sums " + ", ".join(f"{v:,.2f} in payment {k}" for k, v in sorted(lumps.items())))
        print(f"Plan ({'; '.join(what)}): paid off {pl['payoff']} ({pl['months']} payments), "
              f"interest {pl['total_interest']:,.2f}")
        ms = pl["months_saved"]
        if ms >= 0 and pl["interest_saved"] >= 0:
            print(f"  Saves {pl['interest_saved']:,.2f} interest and {ms} months ({ms // 12} y {ms % 12} m)"
                  + (f"; every 100 of extra saves {pl['interest_saved_per_100_extra']:,.2f}" if pl.get("interest_saved_per_100_extra") else ""))
        else:
            print(f"  WARNING: this plan costs {-pl['interest_saved']:,.2f} MORE interest and takes {-ms} months longer than the baseline")
    if a.yearly:
        print(f"
Year-by-year ({'plan' if scenario else 'baseline'}):")
        print(f"{'Year':>4} {'Paid':>12} {'Interest':>12} {'Principal':>12} {'Balance':>12}")
        for y in yearly:
            print(f"{y['year']:>4} {y['paid']:>12,.2f} {y['interest']:>12,.2f} {y['principal']:>12,.2f} {y['end_balance']:>12,.2f}")
    if a.schedule:
        print(f"
Schedule written to {a.schedule} ({len(rows)} rows)")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

---
name: srt-subtitle-quality-checker
description: Checks SRT and WebVTT subtitle files for broken or overlapping timings, numbering gaps, empty cues, reading speed above a characters-per-second limit, long or extra lines, cues that flash by or linger, unbalanced tags, and sound labels, then rewrites and retimes the problem cues and can shift the whole file. Use when a user shares subtitles or captions and asks "check my subtitles", "why are these captions hard to read?", "fix the timing", or "make these subtitles follow the guidelines".
---

# SRT Subtitle Quality Checker

You help video makers, translators, and accessibility teams ship subtitles that people can actually read. You find timing errors that break players, cues that appear too briefly or carry too much text, and lines that are too long, and you fix them by rewriting the text more concisely and adjusting times, without changing the meaning.

## Files in this skill

- `scripts/check_subtitles.py` - parses SRT and WebVTT, checks timing, numbering, reading speed, line length, line count, duration, gaps, tags, and sound labels, and can shift every timestamp (Python 3 standard library only)
- `references/subtitle-guidelines.md` - common limits for reading speed, line length, duration, gaps, line breaks, and when to use SDH labels
- `references/condensing-techniques.md` - how to shorten subtitle text without losing meaning, and how to retime cues
- `templates/subtitle-review.md` - the review report to return
- `examples/example-workshop-video.md` - a worked review of a short tutorial video

## Workflow

### 1. Collect the facts
Ask, or assume and say so:
- The file (SRT or VTT) and the video length; frame rate if known (24, 25, or 30 fps).
- Audience and style guide: general adult viewers, children, a platform guide, or the client's own limits.
- Subtitle type: same-language captions, translation, or SDH (for deaf and hard-of-hearing viewers, with sound labels).
- Whether you may rewrite text or only retime it.

### 2. Run the checker
```bash
python3 scripts/check_subtitles.py movie.srt
python3 scripts/check_subtitles.py movie.srt --max-cps 15 --max-line 37   # children or stricter guides
python3 scripts/check_subtitles.py movie.vtt --json
python3 scripts/check_subtitles.py movie.srt --shift -1200 > movie-synced.srt   # whole file 1.2 s earlier
```
Defaults: 17 characters per second, 42 characters per line, 2 lines, 0.833 to 7 seconds on screen, 83 ms minimum gap. Pick limits from `references/subtitle-guidelines.md` to match the audience. If you cannot run the script, check the cues by hand: duration, characters divided by seconds, longest line, and overlaps with the next cue.

### 3. Fix in this order
1. HIGH findings first: overlaps, out-of-order cues, end before start, bad timestamps, empty cues. These break players or hide text.
2. Reading speed: extend the cue into free time before or after it (respect the minimum gap and shot changes the user mentions), otherwise condense the text with `references/condensing-techniques.md`, otherwise split the cue in two at a natural pause.
3. Line length and line count: rebreak at natural phrase boundaries; keep the top line shorter when possible; never break between an article and its noun.
4. Too short or too long on screen: merge very short cues with a neighbor, split long ones.
5. INFO items: renumber, balance tags, remove sound labels from non-SDH files, chain cues (0 ms gap) or leave a visible gap.
Rerun the checker on the corrected file until there are no HIGH findings and every WARN is fixed or explained.

### 4. Deliver
Fill in `templates/subtitle-review.md`: summary with counts before and after, the limits used, a table of changed cues (old and new times and text), and the full corrected file in the same format as the input. Follow the style of `examples/example-workshop-video.md`.

## Rules
- Never change the meaning, tone, or speaker of a line; condense filler, not content.
- Keep names, numbers, and technical terms exactly; if a term is wrong, flag it instead of guessing.
- Timing changes must stay in sync with the speech: extend a cue only into silence, by at most about 0.5 s before speech starts or 1 s after it ends, unless the user allows more.
- Keep the input format (SRT stays SRT, VTT stays VTT) and the original encoding (UTF-8).
- Say clearly which findings you could not fix without hearing the audio or seeing the video.
FILE:references/subtitle-guidelines.md
# Subtitle guidelines: common limits

Different broadcasters and platforms publish their own style guides. The values below are common starting points; always prefer the client's or platform's guide when one exists, and say which limits you used.

## Reading speed (characters per second, CPS)

CPS = visible characters in the cue (letters, digits, spaces, punctuation; not tags) divided by seconds on screen.

| Audience | Typical CPS limit |
|---|---|
| General adult viewers, same-language or translated | 15 to 17 |
| Fast-paced adult content where the guide allows it | up to 20 |
| Children (around 6 to 11 years) | 12 to 13 |
| Learners of the language, SDH with heavy sound labels | 13 to 15 |

Words per minute is an older measure; around 160 to 180 wpm corresponds to about 15 to 17 CPS in English.

## Line length and line count

- 37 to 42 characters per line for most Latin-script languages; 42 is the most common modern limit.
- Maximum 2 lines per cue. A third line covers the picture and is hard to read.
- Use one line when the text fits on one line; break into two only when needed.

## Duration on screen

- Minimum: about 5/6 of a second (20 frames at 24 fps), even for a single word, so the eye registers it.
- Maximum: about 7 seconds. Longer cues get reread and feel stuck; split them.

## Gaps between cues

- Chained cues: 0 ms gap is fine when the speech is continuous.
- Otherwise leave at least 2 frames (83 ms at 24 fps, 80 ms at 25 fps) so viewers notice that the text changed.
- Gaps between 1 ms and 2 frames cause a visible flicker and should be closed or widened.

## Line breaks

Break lines at natural linguistic units:
- After punctuation (comma, full stop) when possible.
- Before conjunctions (and, but, because) and prepositions.
- Never between an article and its noun, an adjective and its noun, a first and last name, or a verb and its auxiliary.
- Prefer a pyramid shape (shorter top line) when both breaks are equally good.

## Timing to speech and shots

- Start the cue when the speech starts (a few frames early is fine), end it no more than about 1 second after the speech ends.
- Avoid carrying a cue across a hard shot change; end it a couple of frames before the cut or start it after.

## SDH and captions

- Sound labels like [door slams] or (MUSIC) and speaker IDs belong in SDH/closed captions, not in standard translated subtitles.
- Keep labels short, lower case in square brackets is the most common modern style, and place them where the sound happens.

## Formatting

- Italics for off-screen voices, voice-over, songs, and foreign words, if the guide uses them. Every opening tag needs a closing tag in the same cue.
- No full stops at the end of single-line fragments is a style choice; follow the guide.
- SRT: cue number, timestamp line `00:01:02,500 --> 00:01:04,000`, text, blank line. VTT: `WEBVTT` header, optional cue id, timestamps with a dot `00:01:02.500`.
FILE:references/condensing-techniques.md
# Condensing and retiming subtitles

When a cue is too fast to read, try these in order. Stop as soon as the cue fits the limits.

## 1. Use free time first (no text change)

- Look at the gap before and after the cue. Extend the start up to about 0.5 s earlier if nobody else is speaking, and the end up to about 1 s later if the next cue starts later.
- Keep the minimum gap (2 frames) to the neighbors, or chain at 0 ms.
- Required time for a cue = characters / CPS limit. Example: 68 characters at 17 CPS need 4.0 s.

## 2. Cut filler, keep content

Remove words that the viewer hears or sees anyway:
- Hesitations and fillers: "well", "you know", "I mean", "um", "so, basically".
- Repetitions: "very, very" -> "very"; false starts.
- Greetings and names already obvious from the picture.
- Tag questions when tone is clear: "It's ready, isn't it?" -> "It's ready?" only if the meaning stays.

## 3. Use shorter forms

| Long | Short |
|---|---|
| we are going to | we'll |
| at this point in time | now |
| in order to | to |
| a large number of | many |
| it is not possible to | you can't |
| I would like to show you | let me show you |
| due to the fact that | because |

Contractions are usually fine in subtitles; follow the guide for formal content.

## 4. Simplify structure

- Turn passive into active: "The bowl was cleaned by the artist" -> "The artist cleans the bowl".
- Replace a clause with a single word when possible.
- Split one long sentence into two shorter cues at a natural pause.

## 5. Split or merge cues

- Split a cue longer than about 7 s, or one with a 3rd line, at a pause or punctuation; give each half time in proportion to its characters.
- Merge a cue under about 0.8 s with its neighbor when it is the same speaker and the result fits the limits.

## What never to cut

- Names, numbers, quantities, dates, technical terms, and negations ("not", "never").
- Words that carry the joke, the twist, or the emotion of the line.
- Information the viewer needs later in the video.

## Retiming the whole file

If every cue is early or late by the same amount, shift the whole file instead of editing cues:

```bash
python3 scripts/check_subtitles.py movie.srt --shift 1500 > movie-shifted.srt    # 1.5 s later
python3 scripts/check_subtitles.py movie.srt --shift -800 > movie-shifted.srt    # 0.8 s earlier
```

If the drift grows over time (in sync at the start, late at the end), the frame rate is probably wrong (for example 23.976 vs 25 fps); a constant shift will not fix it. Say so and ask for the frame rate of the video.
FILE:templates/subtitle-review.md
# Subtitle review: file_name

**Video:** video_title (duration, fps fps)
**Type:** translation / same-language captions / SDH
**Limits used:** cps chars/s, line chars/line, lines lines, min_dur to max_dur s on screen, gap ms minimum gap (source_of_limits)

## Summary

| | Before | After |
|---|---|---|
| Cues | | |
| HIGH | | |
| WARN | | |
| INFO | | |
| Average chars/s | | |

Main problems in one or two sentences.

## Changes

| Cue | Problem | Old time | New time | Old text | New text |
|---|---|---|---|---|---|
| | | | | | |

## Not fixed (needs audio or video)

- Cue ..., reason ...

## Notes for the editor

- Style choices made (italics, contractions, labels).
- Anything to check against the picture (shot changes, on-screen text).

## Corrected file

```
(full corrected SRT or VTT here, same format as the input)
```
FILE:examples/example-workshop-video.md
# Example: subtitle review of a short tutorial video

## User request

"Here are the English subtitles for our 25-second kintsugi workshop clip. Viewers say they can't keep up. Can you check them and fix what's wrong? General adult audience, normal subtitles, not SDH."

## Input (excerpt of interview.srt)

```
2
00:00:03,250 --> 00:00:04,000
Today we are going to look at how to repair a cracked ceramic bowl with gold.

3
00:00:03,900 --> 00:00:06,500
[HAMMER TAPPING]
First, clean the edges.

5
00:00:07,000 --> 00:00:16,000
<i>This technique is called kintsugi.
```

## Checker run

```
$ python3 scripts/check_subtitles.py interview.srt
interview.srt (SRT): 8 cues, 00:00:01,000 to 00:00:24,000, avg 16.3 chars/s, avg 2.37 s on screen
  HIGH 3  WARN 9  INFO 3
  HIGH overlap          cue 3 @ 00:00:03,900: overlaps the previous cue by 100 ms; end the previous cue at 00:00:03,817
  HIGH end-before-start cue 8 @ 00:00:21,000: ends at 00:00:20,500, not after its start
  HIGH empty-cue        cue 9 @ 00:00:22,000: cue has no visible text
  WARN too-short        cue 2 @ 00:00:03,250: on screen 0.75 s (minimum 0.83 s)
  WARN reading-speed    cue 2 @ 00:00:03,250: 102.7 chars/s (limit 17); needs 4.53 s on screen or about 64 fewer chars
  ...
```

## Review (filled template, shortened)

**Limits used:** 17 chars/s, 42 chars/line, 2 lines, 0.833 to 7 s, 83 ms gap (common general-audience values; no client guide given).

| | Before | After |
|---|---|---|
| Cues | 8 | 8 |
| HIGH | 3 | 0 |
| WARN | 9 | 0 |
| INFO | 3 | 0 |

Main problems: cue 2 carried a whole sentence for under a second, two cues had broken times, a 9-second cue lingered, and cue 7 had three long lines. All fixed by condensing filler, using the silence after the speech, and splitting one cue.

| Cue | Problem | Old time | New time | Old text | New text |
|---|---|---|---|---|---|
| 2 | 102.7 chars/s, 77-char line, overlap with 3 | 03,250-04,000 | 03,300-06,600 | Today we are going to look at how to repair a cracked ceramic bowl with gold. | Today we'll repair a cracked bowl / with lacquer and gold. |
| 3 | sound label in non-SDH file, overlap | 03,900-06,500 | 06,700-08,200 | [HAMMER TAPPING] / First, clean the edges. | First, clean the edges. |
| 4 (was 5) | 9 s on screen, unclosed italics, numbering gap | 07,000-16,000 | 08,300-11,000 | `<i>`This technique is called kintsugi. | `<i>`This technique is called kintsugi.`</i>` |
| 5 (was 6) | 0.4 s on screen | 16,000-16,400 | 16,000-16,900 | Okay. | Okay. |
| 6 and 7 (was 7) | 56 chars/s, 3 lines, 67-char line | 17,000-19,000 | 17,000-21,000 and 21,100-22,800 | You will need lacquer, a fine brush, and gold powder, and patience, / lots of patience, / because each layer must dry. | You'll need lacquer, a fine brush, / gold powder, and lots of patience. + Each layer must dry first. |
| 8 (was 8) | ends before it starts | 21,000-20,500 | 22,900-24,000 | Let's start. | Let's start. |
| 9 | empty cue | 22,000-24,000 | removed | | |

Note: the old cue 2 was shortened ("look at how to", "ceramic") only where the picture already shows it; "lacquer" was added because the speaker names it a few seconds later and the viewer needs it.

**Not fixed:** none, but please confirm against the video that the speaker pauses after "gold" (cue 2 now runs 2.6 s longer, into what looks like silence) and that "Let's start." is spoken at about 22.9 s.

Corrected file rechecked:

```
$ python3 scripts/check_subtitles.py interview-fixed.srt
interview-fixed.srt (SRT): 8 cues, 00:00:01,000 to 00:00:24,000, avg 14.5 chars/s, avg 2.17 s on screen
  HIGH 0  WARN 0  INFO 0
  no problems found
```
FILE:scripts/check_subtitles.py
#!/usr/bin/env python3
"""Check SRT or WebVTT subtitle files for timing and readability problems.

Usage:
  python3 check_subtitles.py FILE [FILE ...] [options]
  python3 check_subtitles.py - < movie.srt          (read stdin)

Options:
  --max-cps N        maximum characters per second (default 17)
  --max-line N       maximum characters per line (default 42)
  --max-lines N      maximum lines per cue (default 2)
  --min-dur S        minimum cue duration in seconds (default 0.833, 20 frames at 24 fps)
  --max-dur S        maximum cue duration in seconds (default 7.0)
  --min-gap MS       minimum gap between cues in milliseconds (default 83, 2 frames at 24 fps)
  --shift MS         print the file with every timestamp shifted by MS (may be negative) and exit
  --json             print findings as JSON
  --fail-on LEVEL    exit 1 if any finding is at least LEVEL: high (default), warn, info

Findings: HIGH = broken or overlapping timing, unreadable numbering, empty cue;
WARN = reading speed, line length, too many lines, too short or long on screen;
INFO = tiny gaps, unbalanced tags, hearing-impaired brackets, statistics.
Exit codes: 0 ok, 1 findings at or above --fail-on, 2 usage or parse error.
Python 3 standard library only.
"""
import json
import math
import re
import sys

TS = re.compile(r"^\s*(\d{1,2}:)?(\d{1,2}):(\d{2})[,.](\d{1,3})\s*-->\s*(\d{1,2}:)?(\d{1,2}):(\d{2})[,.](\d{1,3})(.*)$")
TAG = re.compile(r"</?[^>]+>|\{\[^}]*\}")
LEVELS = {"info": 0, "warn": 1, "high": 2}


def to_ms(h, m, s, ms):
    h = int(h[:-1]) if h else 0
    return ((h * 60 + int(m)) * 60 + int(s)) * 1000 + int(ms.ljust(3, "0"))


def fmt(ms, vtt=False):
    sign = "-" if ms < 0 else ""
    ms = abs(ms)
    h, rem = divmod(ms, 3600000)
    m, rem = divmod(rem, 60000)
    s, rem = divmod(rem, 1000)
    sep = "." if vtt else ","
    return f"{sign}{h:02d}:{m:02d}:{s:02d}{sep}{rem:03d}"


def parse(text):
    """Return (cues, errors, is_vtt). Each cue: dict(index, start, end, lines, line_no)."""
    text = text.replace("
", "
").replace("
", "
").lstrip("\ufeff")
    is_vtt = text.lstrip().startswith("WEBVTT")
    blocks = re.split(r"
\s*
", text.strip("
"))
    cues, errors = [], []
    line_no = 1
    for block in blocks:
        lines = block.split("
")
        start_line = line_no
        line_no += len(lines) + 1
        if is_vtt and (lines[0].startswith("WEBVTT") or lines[0].startswith("NOTE") or lines[0].startswith("STYLE") or lines[0].startswith("REGION")):
            continue
        ts_i = next((i for i, ln in enumerate(lines[:3]) if "-->" in ln), None)
        if ts_i is None:
            errors.append({"level": "high", "rule": "unparsed-block", "line": start_line,
                           "message": f"block without a timestamp line: {lines[0][:50]!r}"})
            continue
        m = TS.match(lines[ts_i])
        if not m:
            errors.append({"level": "high", "rule": "bad-timestamp", "line": start_line + ts_i,
                           "message": f"cannot read timestamp {lines[ts_i].strip()!r} (expected 00:01:02,500 --> 00:01:04,000)"})
            continue
        g = m.groups()
        index = lines[0].strip() if ts_i == 1 else None
        cues.append({"index": index, "start": to_ms(*g[0:4]), "end": to_ms(*g[4:8]),
                     "lines": [ln for ln in lines[ts_i + 1:]], "line_no": start_line})
    return cues, errors, is_vtt


def visible(line):
    return TAG.sub("", line).strip()


def check(cues, errors, opts, is_vtt):
    out = list(errors)

    def add(level, rule, cue, msg):
        out.append({"level": level, "rule": rule, "line": cue["line_no"],
                    "cue": cue["index"] or "-", "time": fmt(cue["start"], is_vtt), "message": msg})

    if not is_vtt:
        expected = 1
        for c in cues:
            if c["index"] is None or not c["index"].isdigit():
                add("high", "bad-number", c, f"cue number missing or not a number: {c['index']!r}")
            elif int(c["index"]) != expected:
                add("warn", "numbering", c, f"cue number {c['index']} but expected {expected} (renumber the file)")
                expected = int(c["index"])
            expected += 1
    prev = None
    for c in cues:
        dur = (c["end"] - c["start"]) / 1000
        text_lines = [visible(ln) for ln in c["lines"] if visible(ln)]
        chars = sum(len(ln) for ln in text_lines)
        if c["end"] <= c["start"]:
            add("high", "end-before-start", c, f"ends at {fmt(c['end'], is_vtt)}, not after its start")
        if not text_lines:
            add("high", "empty-cue", c, "cue has no visible text")
        if prev is not None:
            gap = c["start"] - prev["end"]
            if c["start"] < prev["start"]:
                add("high", "out-of-order", c, f"starts before the previous cue ({fmt(prev['start'], is_vtt)}); sort by time")
            elif gap < 0:
                add("high", "overlap", c, f"overlaps the previous cue by {-gap} ms; end the previous cue at {fmt(c['start'] - opts['min_gap'], is_vtt)}")
            elif 0 < gap < opts["min_gap"]:
                add("info", "tiny-gap", c, f"only {gap} ms after the previous cue; use 0 ms (chained) or at least {opts['min_gap']} ms so the change is visible")
        if c["end"] > c["start"] and text_lines:
            if dur < opts["min_dur"]:
                add("warn", "too-short", c, f"on screen {dur:.2f} s (minimum {opts['min_dur']:.2f} s)")
            if dur > opts["max_dur"]:
                add("warn", "too-long", c, f"on screen {dur:.2f} s (maximum {opts['max_dur']:.1f} s); split it or shorten the time")
            cps = chars / dur if dur > 0 else float("inf")
            if cps > opts["max_cps"]:
                need = chars / opts["max_cps"]
                cut = max(1, math.ceil(chars - opts["max_cps"] * dur))
                add("warn", "reading-speed", c, f"{cps:.1f} chars/s (limit {opts['max_cps']:g}); needs {need:.2f} s on screen or about {cut} fewer chars")
        for ln in text_lines:
            if len(ln) > opts["max_line"]:
                add("warn", "line-length", c, f"line has {len(ln)} chars (limit {opts['max_line']}): {ln[:60]!r}")
        if len(text_lines) > opts["max_lines"]:
            add("warn", "too-many-lines", c, f"{len(text_lines)} lines (limit {opts['max_lines']})")
        raw = " ".join(c["lines"])
        for tag in ("i", "b", "u"):
            if len(re.findall(rf"<{tag}>", raw, re.I)) != len(re.findall(rf"</{tag}>", raw, re.I)):
                add("info", "unbalanced-tag", c, f"<{tag}> tags are not balanced in this cue")
        if re.search(r"\[[^\]]+\]|\([A-Z][A-Z ]+\)", raw):
            add("info", "sdh-label", c, "contains a sound or speaker label in brackets; keep it only in SDH/CC files")
        prev = c
    return out


def stats(cues, is_vtt=False):
    if not cues:
        return {}
    total_chars = sum(len(visible(ln)) for c in cues for ln in c["lines"])
    total_time = sum(max(c["end"] - c["start"], 0) for c in cues) / 1000
    return {"cues": len(cues), "first": fmt(cues[0]["start"], is_vtt), "last_end": fmt(max(c["end"] for c in cues), is_vtt),
            "avg_cps": round(total_chars / total_time, 1) if total_time else None,
            "avg_duration_s": round(total_time / len(cues), 2)}


def shift_text(text, delta):
    def rep(m):
        g = m.groups()
        vtt = "." in m.group(0).split("-->")[0]
        a = max(to_ms(*g[0:4]) + delta, 0)
        b = max(to_ms(*g[4:8]) + delta, 0)
        return f"{fmt(a, vtt)} --> {fmt(b, vtt)}{g[8]}"
    return "
".join(TS.sub(rep, ln) if "-->" in ln else ln
                     for ln in text.replace("
", "
").split("
"))


def main(argv):
    opts = {"max_cps": 17.0, "max_line": 42, "max_lines": 2, "min_dur": 0.833, "max_dur": 7.0,
            "min_gap": 83, "json": False, "fail_on": "high", "shift": None}
    files = []
    it = iter(argv)
    try:
        for a in it:
            if a == "--json":
                opts["json"] = True
            elif a in ("--max-cps", "--min-dur", "--max-dur"):
                opts[a[2:].replace("-", "_")] = float(next(it))
            elif a in ("--max-line", "--max-lines", "--min-gap", "--shift"):
                opts[a[2:].replace("-", "_")] = int(next(it))
            elif a == "--fail-on":
                opts["fail_on"] = next(it).lower()
                if opts["fail_on"] not in LEVELS:
                    raise ValueError("--fail-on must be high, warn, or info")
            elif a in ("-h", "--help"):
                print(__doc__)
                return 0
            elif a.startswith("--"):
                raise ValueError(f"unknown option {a}")
            else:
                files.append(a)
    except (StopIteration, ValueError) as e:
        print(f"error: {e or 'option needs a value'}", file=sys.stderr)
        return 2
    if not files:
        print("error: give at least one .srt or .vtt file, or - for stdin", file=sys.stderr)
        return 2
    report, worst = [], -1
    for f in files:
        try:
            text = sys.stdin.read() if f == "-" else open(f, encoding="utf-8-sig").read()
        except (OSError, UnicodeDecodeError) as e:
            print(f"error: cannot read {f}: {e}", file=sys.stderr)
            return 2
        if opts["shift"] is not None:
            sys.stdout.write(shift_text(text, opts["shift"]))
            return 0
        cues, errors, is_vtt = parse(text)
        if not cues:
            print(f"error: {f}: no subtitle cues found (is this an SRT or WebVTT file?)", file=sys.stderr)
            return 2
        findings = check(cues, errors, opts, is_vtt)
        for x in findings:
            worst = max(worst, LEVELS[x["level"]])
        report.append({"file": f, "format": "vtt" if is_vtt else "srt", "stats": stats(cues, is_vtt), "findings": findings})
    if opts["json"]:
        print(json.dumps(report, indent=2))
    else:
        for r in report:
            counts = {lv: sum(1 for x in r["findings"] if x["level"] == lv) for lv in ("high", "warn", "info")}
            st = r["stats"]
            print(f"{r['file']} ({r['format'].upper()}): {st['cues']} cues, {st['first']} to {st['last_end']}, "
                  f"avg {st['avg_cps']} chars/s, avg {st['avg_duration_s']} s on screen")
            print(f"  HIGH {counts['high']}  WARN {counts['warn']}  INFO {counts['info']}")
            for x in sorted(r["findings"], key=lambda x: (-LEVELS[x["level"]], x["line"])):
                where = f"cue {x.get('cue', '-')} @ {x['time']}" if "time" in x else f"line {x['line']}"
                print(f"  {x['level'].upper():<4} {x['rule']:<16} {where}: {x['message']}")
            if not r["findings"]:
                print("  no problems found")
    return 1 if worst >= LEVELS[opts["fail_on"]] else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

Photoreal photograph of the same restored compact 1960s-style step van food truck from step 2, now during evening service at a riverside night market at blue hour, seen in a rear right three-quarter view from standing eye level (1.6 m) about 9 m away, 35mm lens, 16:9 landscape composition with the whole truck in frame, slightly left of center. Keep every fixed design detail identical to step 2: a short boxy step van body about 5.5 m long with softly rounded corners, a rounded cab roof, and a flat box roof; two-tone paint, glossy cream on the upper half and deep teal on the lower half, separated by a thin copper-orange stripe running all around the body just below the windows; black tires with large polished chrome hubcaps; a chrome front bumper and round headlights at the front. The rear of the truck now faces the camera on the left: two tall cream rear doors, each with a small round porthole window, a chrome rear bumper, and two small round red tail lights glowing softly; the front of the truck points away to the right. On the right side (the customer side, seen at an angle on the right of the frame): the large rectangular serving window cut into the cream upper body, with a big flat deep teal awning panel raised above it and held horizontally on thin silver struts, slightly wider than the window and sticking up above the roofline; the window has a brushed stainless steel counter shelf and a bright, warmly lit interior with shelves of glass jars, bottles, small copper pots, a coffee machine, and a small vase of pink and yellow flowers on the counter, and a small dark chalkboard hanging inside; a small round silver badge sits on the teal lower body near the rear wheel. Warm light from the open window spills onto the ground. A cook in a dark apron works behind the counter, softly blurred. In front of the window, a short queue of softly blurred customers seen from behind. Setting: a riverside promenade with a stone embankment, a dark river reflecting city lights in the background, other market stalls with warm lanterns and string lights out of focus. Deep blue sky with the last glow on the horizon, warm amber light from the window mixed with cool blue dusk, wet-looking cobblestones with reflections, lively but relaxed mood, realistic paint, chrome, and glass textures, evening street photography. No readable text, no letters, no numbers, no license plate characters, no real brand logos, no faces in focus.

Photoreal lifestyle photograph of a restored compact 1960s-style step van food truck parked in a sunny city plaza at weekday lunchtime, seen in a front right three-quarter view from standing eye level (1.6 m) about 9 m away, 35mm lens, 16:9 landscape composition with the whole truck in frame, slightly right of center. Fixed design details: a short boxy step van body about 5.5 m long with softly rounded corners and a flat roof; two-tone paint, glossy cream on the upper half and deep teal on the lower half, separated by a thin copper-orange stripe running all around the body at the height of the window bottoms; a flat front with a large two-pane windshield, two round chrome headlights, a simple chrome horizontal grille bar, and a chrome front bumper; black tires with cream-painted steel wheels and small chrome hubcaps. On the right side (the customer side, facing the camera): a large rectangular serving hatch centered on the side, its top-hinged teal panel propped open as an awning on two chrome struts, the underside of the awning painted copper-orange; a brushed stainless steel counter shelf along the bottom of the hatch with a small pot of basil and a glass jar of lemons on it; to the left of the hatch, toward the front, a round copper-orange emblem of a simple sun over a wheat stalk, with no letters; to the right of the hatch, toward the rear, a plain dark slate menu board with no writing, only three small hand-drawn white icons of a flatbread, a lemon, and a glass. Along the top edge of the roof on the customer side runs a line of warm globe string lights (switched off in daylight). On the roof at the front sits a long wooden planter box with green herbs, and a small round silver vent near the back. On the ground in front of the hatch: a low natural-wood step platform and a teal A-frame stand with a blank front. The plaza has pale stone paving, plane trees with dappled shade, a couple of cafe tables, and blurred passers-by in the far background only. Bright midday sun with soft dappled shadows, fresh and friendly mood, realistic paint reflections and metal textures, commercial street photography. No readable text, no letters, no numbers, no license plate characters, no real brand logos, no faces in focus.

A mid-century modern gouache illustration of a small mountaintop astronomical observatory in a red rock desert at dusk, wide 16:9 landscape composition, painted in flat, opaque gouache with visible brush texture and slightly chalky matte color. In the center right, on a flat mesa top, stands a white observatory building with a round silver-grey dome, its long shutter slit open and a telescope tube just visible pointing at the sky; beside it a low rectangular block building with one warm yellow lit window and a small radio antenna. A thin winding road with simple white dashes climbs the mesa in loose switchbacks from the lower left. The desert below is built from layered flat shapes: terracotta and rust orange mesas, a band of dusty pink cliffs, ochre sand dunes, and rounded sage-green shrubs and a few tall saguaro-like cactus silhouettes in the foreground on the left. The sky is a smooth gradient from deep teal and indigo at the top to warm apricot and coral at the horizon, scattered with small four-pointed stars, a thin crescent moon, and a faint band of the Milky Way rendered as soft dry-brush speckles. Long purple shadows stretch across the sand. Limited palette of teal, indigo, coral, rust, ochre, cream, and sage green, simplified geometric shapes, clean edges with a little hand-painted wobble, subtle paper grain, the look of a 1960s science book illustration or national park poster without any lettering. Calm, optimistic, wonder-filled mood. No people, no text, no letters, no logos, no border, no watermark.

An extreme close-up macro photograph of an orb spider web covered in morning dew, stretched between two arching stems of dry meadow grass, composed as a wide 16:9 landscape. The web's spiral threads run diagonally across the frame, strung with hundreds of perfectly round dewdrops of different sizes, from tiny beads to large clear spheres; in the sharpest drops in the foreground, each sphere holds a tiny upside-down reflection of the meadow behind: a golden sunrise sky, a line of distant trees, and a few red poppies. The focus plane is razor thin and falls on one row of drops in the left third, which sparkle with pinpoint highlights and fine rainbow refraction at their edges, while the rest of the web melts into soft blur. The background is a smooth, creamy bokeh of warm gold, peach, and soft green from the low sun shining through mist over the meadow, with large round out-of-focus highlights in the upper right. A small garden spider sits far away near the edge of the web, out of focus and tiny, barely more than a dark speck. A few grass seed heads in the foreground are also blurred, framing the bottom edge. Backlit low golden-hour sunlight, gentle haze, high dynamic range, natural colors, crisp water texture, nature magazine macro photography taken with a 100mm macro lens at f/2.8, serene and delicate mood. No people, no text, no watermark.

A wide, slightly elevated photograph of an ancient Roman floor mosaic uncovered in the courtyard of a Mediterranean villa ruin, the mosaic filling most of the frame in a 16:9 landscape composition. The mosaic shows a lively marine scene made of thousands of small hand-cut stone and glass tesserae: in the center a large octopus in terracotta red and burnt orange with curling tentacles outlined in dark charcoal tiles, its suckers picked out in cream; around it swim striped sea bream, a moray eel, a lobster, squid, and a leaping dolphin in slate grey, ochre, and muted teal; at the top two small wooden fishing boats with square sails and oarsmen drawn as simple dark silhouettes cast a net that curves across the scene; the water is rendered in rows of pale cream and soft blue-grey tesserae laid in gentle wavy lines that follow the shapes of the animals. A border of black and white wave scroll pattern and a braided guilloche band in red, ochre, and cream frames the whole panel. The surface is authentically aged: slightly uneven tiles, a few missing patches showing the grey mortar bed, hairline cracks, faded colors in one corner, a light dusting of sand, and small tufts of dry grass at the broken edge. Low warm late-afternoon sunlight rakes across the floor from the left, making each tessera catch the light and cast a tiny shadow, with the soft shadow of a broken column falling over one corner. Around the edges: weathered limestone paving, the base of a column, and a few terracotta pot shards. Archaeological documentary photography, true colors, crisp detail, calm and timeless mood. No people, no text, no letters, no inscriptions, no signatures, no watermark.

Act as a food truck concept designer and brand designer, and as a visualization art director. I will describe the street food business I want to start. You will turn it into a clear food truck concept: the vehicle, the exterior design, the service layout, and the brand look, with a list of fixed design details plus two ready-to-use image prompts that show the SAME truck at two different times and from two different viewpoints, so the two AI images look like photos of one real vehicle.

Food and business idea: Mediterranean flatbreads and fresh lemonade, quick lunch service, about 60 meals an hour
Vehicle type: a restored compact 1960s-style step van, about 5.5 m long
Where it will trade: city plazas at lunch on weekdays, riverside night markets on weekends
Brand personality: sunny, friendly, a little retro, clean and trustworthy
Colors I like or dislike: like teal, cream, and copper; avoid red and yellow fast-food colors
Must have: a large serving hatch with an awning, a small menu board, string lights for evenings, space for a queue
Budget level: modest, a used van with a professional fit-out and a hand-painted look
View A: sunny weekday lunchtime in a city plaza with plane trees, front right three-quarter view
View B: evening service at a riverside night market, lights on, rear right three-quarter view

Please produce:

1. Concept
   - Truck name idea (for my use only, it will not appear in the images) and a two-sentence story of how the truck should feel to a customer.
   - Vehicle and exterior: body shape, paint scheme with where each color goes, wheels and chrome details, roof details, and the emblem as a simple wordless symbol.
   - Service side layout: hatch size and position, awning, counter, menu board, pickup point, payment point, queue direction, and lighting, described from the customer's side.
   - Palette: 6 named colors (simple names like "deep teal" or "copper orange") and where each one is used.
   - Materials and finishes: paint finish, stainless steel, wood, fabric, and light fittings.

2. Fixed design details (the consistency list)
   A numbered list of 12 to 16 details that must look identical in every image: body shape and proportions, paint split and stripe, front details (headlights, grille, bumper), wheels, the serving hatch and awning with exact position, the menu board, the emblem and where it sits, roof items, lights, rear windows and doors, and any props on the ground, each with its exact position. Write each one as a short, concrete phrase an image generator can follow (for example "copper-orange round emblem of a sun over a wheat stalk on the right side, behind the front door").

3. Image prompt A: the base view
   One detailed prompt for an AI image generator: photoreal photography of the truck from the view A position, in view A light and setting. Include every fixed detail visible from there in its correct position (left and right as seen from the camera), the camera height and lens, lighting, mood, and a 16:9 landscape composition. End with exclusions (no people's faces in focus, no readable text, no logos of real brands).

4. Image prompt B: the second view
   One detailed prompt for view B, written for a text-only image generator that cannot see image A: restate ALL fixed details again in full words (never "same as before"), place each one correctly for the new camera position, describe what is newly visible (for example the rear doors and windows), and change only the time of day, setting, and lighting. Keep the paint, proportions, emblem, and props identical.

5. Consistency checklist
   Ten yes/no checks to compare image B against image A (for example "Is the stripe between the cream and teal still copper-orange and at the same height?").

6. Practical notes
   A short list covering the kitchen layout behind the hatch for the stated meals per hour, ventilation and gas or electric power, water tanks, permits and food safety inspections to check locally, a rough fit-out budget split, and three ways to save money without hurting the look.

Rules:
- Keep it buildable for the stated vehicle and budget; flag anything unrealistic or unsafe.
- Use plain color names and concrete shapes; avoid vague words like "fun" or "modern" on their own.
- No readable text, lettering, or numbers anywhere on the truck in the image prompts: menu boards stay blank or show simple drawn food icons only, and the brand appears only as a wordless symbol.
- No brand names, no real people, no copyrighted characters.
- If my description is missing something essential, make a sensible assumption and list it at the top.

Act as a home move planner and countdown coach. You have organized hundreds of household moves, from studio flats to family houses, local and across the country. You turn the chaos of moving into a calm, dated plan: what to book, what to sort, what to pack when, who to notify, and what to do on the day itself. You are practical and reassuring, you think about cash, time, and energy together, and you always plan for the things people forget until the last week.

About my move:
- Moving from and to: a 2-bedroom rented flat on the 3rd floor with no lift, to a small house 40 km away
- Moving date and flexibility: Saturday 14 November, can shift by one week
- Who is moving: two adults, a 6-year-old, and an indoor cat
- Amount of stuff: normal amount for a 2-bedroom flat, full kitchen, a piano, many books
- Movers or DIY: not decided yet, budget is tight but we have bad backs
- Budget for the move: 1500 EUR including everything
- Work and time constraints: both work full-time, evenings and weekends free, can take one day off
- Leaving the old place: must return keys and hand over the flat clean by 30 November to get the deposit back
- Things that worry me most: the piano, keeping the child's routine, losing important documents

Please do the following:
1. Start with a quick reality check: weeks left, the 3 biggest risks for my move, and whether the date and budget look realistic. State any assumption you make.
2. Help me decide movers versus DIY with a short comparison for my situation: estimated cost range, time, physical effort, and risk, plus the specialist items (such as the piano) that should be handled by professionals either way. Give me 5 questions to ask every moving company and what a fair quote must include.
3. Build a week-by-week countdown from today to moving day, with 4 to 8 concrete tasks per week, each with an owner (me, partner, both, child can help) and a time estimate. Include booking movers or a van, ordering boxes, decluttering by room, selling or donating, change-of-address notices, utilities and internet transfer, school and doctor updates, and parking or lift reservations.
4. Give a room-by-room packing order: what to pack first (rarely used) and what to pack last, how many boxes to expect per room, how to label boxes so unpacking is fast, and what goes in the "first night" box and the "documents and valuables" bag that never goes on the truck.
5. Write a notify list grouped by type (government and registration, banks and insurance, utilities, work and school, health, subscriptions and deliveries, friends and family), with a column for when to notify.
6. Plan moving day hour by hour: who is where, care for the child and the cat, loading order, final walkthrough of the old place, and the first two hours in the new home.
7. Cover the handover: a cleaning and repair checklist for getting the deposit back, meter readings and photos to take, and what to keep in writing.
8. Finish with a one-page summary: key dates, the budget split, the 5 things that must not be forgotten, and a "first week in the new home" list.

Rules:
- Use my real dates and constraints; show every deadline as a date, not "a few weeks before".
- Keep each task short and actionable, starting with a verb.
- Be honest about costs as ranges and label them as estimates for my region.
- Include small ways to keep the move calm for a child and a pet.
- If something essential is missing, make a sensible assumption and say so instead of asking many questions.

Photoreal architectural photograph of the same small cedar treehouse cabin and old oak from step 2, now on a snowy winter evening at blue hour, seen from the meadow at the front right instead of from the left, camera at standing eye level (1.6 m) about 14 m away, 35mm lens, vertical lines straight, 16:9 landscape composition with the oak trunk and the whole cabin in frame. Keep every fixed design detail identical to step 2. Host tree: one huge old oak with a massive grey, deeply furrowed trunk and wide flared root buttresses spreading over the ground, splitting into several thick limbs that arch over the cabin roof; it now stands on the left side of the frame, completely bare, its dark branches lined with fresh snow against a deep blue sky. The cabin stands right beside the trunk, to its right, on a low timber deck raised about 0.6 m on short square timber posts. Cabin: a compact two-storey-high single room clad in vertical cedar boards in bright honey brown, under a steep gable roof of dark green standing-seam metal with one small dark box vent on the roof slope, now carrying a soft layer of snow; the gable end faces the camera on the right, plain vertical cedar boards with a narrow green fascia. The long side wall, now seen at an angle on the left, has a row of large dark-framed floor-to-ceiling glass windows and a glass door, all glowing warm amber from inside. The timber deck wraps around the front and the gable side, with simple timber railings of square posts and thin vertical balusters, snow along the top rail, and a wooden slatted lounge chair on the deck dusted with snow. A wide, straight timber staircase with matching railings descends from the front right corner of the deck down to the meadow, now in the right foreground, its treads covered in fresh snow with a line of footprints. Warm globe string lights hang along the deck railing, glowing. At the base: smooth snow over the meadow and around the oak's roots, a bare deciduous forest fading into blue dusk behind. Cool blue-hour light on the snow mixed with warm amber light from the windows and string lights. Palette of honey cedar, dark green, charcoal black window frames, oak grey, warm amber, and snow white. Realistic wood, metal, glass, bark, and snow textures, architecture magazine photography, quiet mood. No people, no text, no logos, no signs.

Photoreal architectural photograph of a small timber treehouse retreat built into a single huge old oak tree, standing in a sloping summer meadow at the edge of a beech forest, seen from the meadow at the front left, camera at standing eye level (1.6 m) about 12 m away, 35mm lens, vertical lines straight, 16:9 landscape composition with the whole tree and treehouse in frame. The oak has a massive grey, deeply furrowed trunk about 1.2 m wide that splits into three thick main limbs above the roof, with a full, dense green summer canopy spreading over the treehouse. A square timber deck about 3.5 m above the ground wraps around the trunk, the trunk rising through the deck behind the cabin; the deck is held by two round natural timber posts at the front corners and four diagonal timber knee braces angled from the trunk. On the deck stands a compact cabin about 3 by 4 m, clad in vertical cedar boards weathered to a warm honey brown, under a steep gable roof of dark green standing-seam metal with the gable end facing the camera. Front wall: a round porthole window high in the gable apex; a large black-framed picture window that wraps around the front left corner of the cabin; and a teal-blue Dutch door, split into upper and lower halves, on the right half of the front wall, with a small black metal lantern beside it. A slim black stove chimney pipe rises from the right side of the roof. The deck has a railing of cedar posts with three horizontal natural ropes between them, warm globe string lights looped along the railing (off in daylight), and two mustard-yellow folding wooden deck chairs at the front. A straight timber staircase with a mid-height landing rises along the right side of the deck from the ground to the front right corner. On the left, a rope swing with a plain wooden seat hangs from a low horizontal oak limb. At the base of the tree: ferns, moss, a few large stones, and a pale gravel path curving through the meadow grass to the foot of the stairs, with wildflowers in white and purple. Warm late-afternoon sunlight from the left, dappled light through the leaves on the cedar walls, soft shadows, clear blue sky glimpsed between branches. Palette of honey cedar, moss green, teal blue, mustard yellow, charcoal black, and oak grey. Realistic wood grain, metal, rope, and bark textures, high-end architecture magazine photography, calm and inviting mood. No people, no text, no logos, no signs.