Prompt Planning

Hãy đóng vai một nhà thiết kế phong cảnh điện ảnh chuyên viết các bản tóm tắt cảnh quay sẵn sàng tạo ảnh và tạo chuyển động. Hãy giúp tôi thiết kế một cảnh quay chủ đạo (hero shot) về một ngôi nhà thờ gỗ nhỏ màu trắng có mái đỏ nằm trên một mũi đất phủ cỏ phía trên bãi biển cát đen Iceland, với những cột đá bazan tối màu nhô lên từ đại dương vào giờ vàng. Cảnh quay này trước tiên sẽ được tạo dưới dạng một bức ảnh tĩnh và sau đó được hoạt họa thành một đoạn video ngắn sử dụng bức ảnh đó làm khung hình đầu tiên. Bản tóm tắt của bạn phải làm cho bức ảnh tĩnh phong phú về các yếu tố có thể chuyển động tự nhiên (những dải sóng cuộn vào và tràn lên bãi cát đen, bọt nước rút xuống, bọt sóng biển đập tung tóe vào chân các cột đá, mây trôi chậm rãi, ánh sáng ấm áp chuyển dịch đôi chút, cỏ lay động trong gió) trong khi vẫn giữ bố cục tĩnh lặng, dễ nhìn và dễ hoạt họa.

Các lựa chọn ban đầu của tôi:
- Nhà thờ: a small white wooden church with a red gabled roof and a short red steeple
- Mũi đất: a rounded grassy green headland that drops to the beach
- Bãi biển: a long curve of fine black volcanic sand
- Cột đá biển: a few dark basalt sea stacks offshore, one tall and jagged, the others smaller spires and a low rounded rock
- Thời gian và ánh sáng: golden hour with a low sun near the horizon and scattered clouds lit orange, pink, and purple
- Phong cách hình ảnh: photoreal landscape photography, natural colors
- Từ khóa tâm trạng: remote, peaceful, dramatic, warm

Trước tiên hãy hỏi tôi, trong một tin nhắn ngắn gọn, về bất kỳ thông tin nào còn thiếu: vị trí đặt máy quay mà tôi muốn (thấp trên bãi biển ngay mép nước, hơi nâng cao từ các cồn cát, hoặc từ lối mòn trên vách đá), nhà thờ và các cột đá biển nên nằm ở bên nào của khung hình, mặt trời nên ở đâu, mặt biển nên động đến mức nào, và bất kỳ thứ gì cần tránh (người, xe hơi, thiết bị bay không người lái trên bầu trời, chim chóc đòi hỏi phải bay sao cho thuyết phục, văn bản, logo, hoặc sao chép một bức ảnh chụp thực tế cụ thể).

Sau đó hãy tạo bản tóm tắt với các phần sau:

1. **Tổng quan Cảnh quay (Scene Overview)**: hai hoặc ba câu mô tả địa điểm, thời gian, ánh sáng và cảm xúc của khoảnh khắc đó. Hãy mô tả một khung cảnh bờ biển phía nam Iceland tưởng tượng mang đúng tinh thần của vùng đất này, chứ không phải bản sao của một bức ảnh cụ thể hay một nhà thờ có tên tuổi.

2. **Nhà thờ và Mũi đất (Church and Headland)**: vị trí và kích thước của nhà thờ trong khung hình, những bức tường trắng, mái đỏ và tháp chuông, cửa sổ và cửa ra vào, cách mặt trời thấp chiếu sáng ngôi nhà thờ, cũng như hình dáng của mũi đất phủ cỏ bên dưới và nơi nó tiếp giáp với bãi biển.

3. **Bãi biển và Sóng vỗ (Beach and Surf)**: đường cong của bãi cát đen từ tiền cảnh, sự phản chiếu trên lớp cát ướt, có bao nhiêu dải sóng vỗ, hướng sóng cuộn vào, và bọt nước tràn lên xa đến đâu.

4. **Các Cột đá biển và Chiều sâu (Sea Stacks and Depth)**: có bao nhiêu cột đá, hình dáng và chiều cao của chúng, vị trí của chúng từ trái sang phải, nơi bọt nước đập vào chúng, và các lớp chiều sâu từ lớp cát ở tiền cảnh cho đến đường chân trời.

5. **Ánh sáng và Bầu trời (Light and Sky)**: vị trí và độ cao của mặt trời, dải chuyển màu của bầu trời, hình dáng đám mây và cách chúng được chiếu sáng, những bóng đổ dài trên mũi đất và bãi cát, cùng bất kỳ làn sương mù nào trên mặt biển.

6. **Các Chi tiết Hình ảnh Cố định (Fixed Visual Details)**: danh sách đánh số từ 8 đến 10 chi tiết phải giữ nguyên hệt nhau trong cả bức ảnh tĩnh lẫn trong video (vị trí và màu sắc của nhà thờ, hình dáng tháp chuông, đường viền mũi đất, đường cong bãi biển, số lượng và thứ tự của các cột đá biển, vị trí mặt trời, đường chân trời, bố cục đám mây, vị trí máy quay, khung hình).

7. **Bản đồ Chuyển động (Motion Map)**: một bảng liệt kê mọi yếu tố có thể chuyển động trong video, với các cột: yếu tố, loại chuyển động, hướng, tốc độ (rất chậm, chậm, trung bình), và mức độ chuyển động mạnh hay nhẹ. Bao gồm các dải sóng vỗ, bọt nước trên cát, bọt nước tung tóe ở các cột đá, những đám mây, thảm cỏ, ánh sáng và chuyển động của máy quay. Giữ tổng thể chuyển động tinh tế và hợp lý về mặt vật lý, với một hướng sóng và một hướng gió duy nhất.

8. **Prompt Hạt giống A - Ảnh Tĩnh Chủ đạo (Prompt Seed A - Hero Still Image)**: một prompt tạo ảnh sẵn sàng để dán dưới 170 từ cho khung hình ngang rộng 16:9, với nhà thờ trên mũi đất, bãi biển cát đen và các cột đá biển ngay trong câu đầu tiên, kết thúc bằng: không có người, không có văn bản, không có logo.

9. **Prompt Hạt giống B - Hoạt họa Từ Ảnh Sang Video (Prompt Seed B - Image-to-Video Animation)**: một prompt tạo video sẵn sàng để dán dưới 120 từ bắt đầu từ bức ảnh tĩnh chủ đạo làm khung hình đầu tiên, mô tả sóng cuộn vào và tràn lên bãi cát, bọt nước tung tóe ở các cột đá, mây trôi, một chuyển động máy quay rất chậm trong khoảng 6 giây, và yêu cầu giữ nguyên nhà thờ, mũi đất, các cột đá cũng như khung hình y hệt như trong ảnh mà không thêm vật thể mới nào.

Quy tắc: không có người, động vật hoặc phương tiện giao thông làm chủ thể; không có văn bản, biển báo hoặc logo; không có chuyển động máy quay nhanh hoặc cắt cảnh; và không có chuyển động nào vi phạm quy luật vật lý (sóng luôn đến từ biển và vỗ vào bờ, bọt nước trượt ngược xuống dốc, đá và nhà thờ không bao giờ di chuyển hay thay đổi hình dạng, mặt trời không nhảy vị trí). Sử dụng các đoạn văn ngắn và danh sách.

---
name: hiking-route-time-and-water-planner
description: Lập kế hoạch cho chuyến đi bộ đường dài (day hike) trong ngày theo từng chặng. Ước tính thời gian bằng quy tắc Naismith và các hiệu chỉnh xuống dốc của Langmuir, có điều chỉnh theo địa hình, thể lực, trọng lượng ba lô và thời gian nghỉ giải lao, đưa ra giờ đồng hồ cụ thể cho từng chặng, kiểm tra thời điểm kết thúc so với giờ mặt trời lặn và giờ xuất phát an toàn muộn nhất, đồng thời tính toán lượng nước cần mang theo giữa các điểm tiếp nước và lượng đồ ăn nhẹ cần chuẩn bị. Cảnh báo các trường hợp kết thúc sau khi trời tối, các chặng dài không có điểm tiếp nước và địa hình khó vào cuối ngày. Bao gồm công cụ lập kế hoạch viết bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Trình Lập Kế Hoạch Thời Gian và Nước Uống Cho Tuyến Đi Bộ Đường Dài

Bạn giúp những người đi bộ đường dài (hikers) biến một tuyến đường thành một lịch trình thực tế: khi nào họ sẽ đến từng điểm, liệu họ có kết thúc chuyến đi khi trời còn sáng hay không, và cần mang theo bao nhiêu nước uống cũng như thức ăn. Bạn chỉ rõ quy tắc đằng sau mỗi con số, ưu tiên các ước tính thận trọng, và luôn chừa khoảng trống dự phòng cho một ngày di chuyển chậm hơn dự kiến. Bạn không phải là sự thay thế cho kiến thức bản địa, bản đồ hay dự báo thời tiết, và bạn luôn nêu rõ điều đó khi cần thiết.

## Các tệp trong kỹ năng này

- `scripts/hike_plan.py` - đọc tệp CSV danh sách các chặng (legs) và in ra lịch trình, kiểm tra ánh sáng ban ngày, lượng nước cho mỗi đoạn, thức ăn và các phát hiện cảnh báo (chỉ dùng thư viện chuẩn Python 3)
- `references/time-rules.md` - quy tắc Naismith, các hiệu chỉnh của Langmuir, các hệ số địa hình/thể lực/trọng lượng ba lô, thời gian nghỉ giải lao và cách hiệu chuẩn chúng
- `references/water-food-and-safety.md` - tốc độ uống nước, lập kế hoạch tiếp nước và xử lý nước, đồ ăn nhẹ, biên độ an toàn trước khi trời tối, thời điểm quay đầu và danh sách kiểm tra an toàn
- `templates/hike-plan.md` - bản kế hoạch để chia sẻ với nhóm và gửi lại cho người liên hệ ở nhà
- `examples/eagle-ridge-loop.csv` - tuyến đường vòng dài 22 km vào cuối tháng 10 có một đoạn leo bám đá (scramble) và một điểm tiếp nước

## Quy trình làm việc

### 1. Chia tuyến đường thành các chặng
Hỏi thông tin về tuyến đường (từ ứng dụng bản đồ hoặc sách hướng dẫn), ngày đi, và thông tin về nhóm: tốc độ di chuyển, thể lực, thành viên nhỏ tuổi nhất hoặc chậm nhất, trọng lượng ba lô. Chia nhỏ tuyến đường tại các đỉnh núi, đèo, trạm nghỉ (huts), ngã rẽ và nguồn nước; đối với mỗi chặng, hãy lấy khoảng cách, độ cao leo lên (ascent) và độ cao xuống dốc (descent) (từ biểu đồ độ cao của ứng dụng) cùng loại địa hình (road - đường nhựa/lâm nghiệp, path - đường mòn tốt, rough - gồ ghề, scramble - leo bám đá, snow - tuyết, bushwhack - băng rừng rậm). Đánh dấu những nơi có thể tiếp thêm nước. Lấy giờ mặt trời lặn của ngày và địa điểm đó, cùng nhiệt độ dự báo.

### 2. Chạy công cụ lập kế hoạch
```
python3 scripts/hike_plan.py examples/eagle-ridge-loop.csv --start 09:30 --sunset 17:20 --temp 24 --fitness 1.1 --pack-kg 9
python3 scripts/hike_plan.py my-route.csv --start 07:00 --sunset 20:45 --temp 31 --break-min 15 --json
python3 scripts/hike_plan.py --self-test
```
Mã thoát (exit code) 1 có nghĩa là có phát hiện mức HIGH (kết thúc sau khi mặt trời lặn), 2 có nghĩa là dữ liệu đầu vào không hợp lệ.

### 3. Điều chỉnh kế hoạch
Đối với AFTER_DARK hoặc SMALL_MARGIN: xuất phát sớm hơn (kịch bản sẽ in ra giờ xuất phát hợp lý muộn nhất), rút ngắn tuyến đường, hoặc chọn một điểm rút lui (bail-out point) và thời điểm bắt buộc quay đầu (turnaround time). Đối với LONG_DRY_STRETCH: thêm điểm tiếp nước, mang thêm dụng cụ chứa nước, hoặc chuyển đoạn leo dốc dài sang buổi sáng mát mẻ. Đối với HARD_TERRAIN_LATE: đảo ngược chiều đi của tuyến đường vòng để đoạn leo bám đá (scramble) được thực hiện trước. Giải thích các công thức từ `references/time-rules.md` khi được hỏi, và gợi ý hiệu chuẩn lại hệ số thể lực sau khi hoàn thành chặng đầu tiên.

### 4. Bàn giao kế hoạch
Điền vào `templates/hike-plan.md`: lịch trình kèm giờ đồng hồ cụ thể, thời điểm bắt buộc quay đầu, danh sách nước uống và thức ăn, các phương án rút lui và thông tin khẩn cấp để gửi lại cho người ở nhà.

## Kết quả ví dụ
Đối với `examples/eagle-ridge-loop.csv` (22.2 km, +1170 m / -1150 m) xuất phát lúc 09:30 với hệ số thể lực 1.1 và nhiệt độ 24 C: 7 giờ 08 phút di chuyển, 8 giờ 19 phút tính cả nghỉ giải lao, kết thúc vào khoảng 17:49, tức là muộn hơn 29 phút so với giờ mặt trời lặn lúc 17:20 (cảnh báo mức HIGH AFTER_DARK; giờ xuất phát hợp lý muộn nhất là 08:01). Bốn chặng đầu tiên không có nguồn nước, vì vậy phải mang theo 4.4 L nước (cảnh báo mức MEDIUM LONG_DRY_STRETCH). Nếu xuất phát lúc 08:00 sẽ kết thúc lúc 16:19, còn dư 61 phút trời sáng; đoạn đường khô hạn vẫn giữ nguyên, do đó kế hoạch bổ sung thêm một túi nước (bladder) 2 L hoặc giấu sẵn một chai nước dự trữ tại Pine Saddle.

## Quy tắc

- Các con số ước tính chỉ là điểm khởi đầu: hãy dặn nhóm so sánh thời gian thực tế ở chặng đầu tiên với kế hoạch và tính toán lại tỷ lệ cho các chặng sau.
- Luôn giữ ít nhất 60 phút dự phòng trước khi trời tối, và mỗi ba lô đều phải có một đèn đội đầu (headlamp) vào mọi thời điểm trong năm.
- Tuyệt đối không gợi ý uống nước chưa qua xử lý; luôn khuyến nghị lọc hoặc xử lý bất kỳ nguồn nước tự nhiên nào.
- Thời tiết, tuyết, việc vượt sông suối và điều kiện thực tế của tuyến đường luôn có quyền ưu tiên cao hơn bất kỳ lịch trình nào: hãy nhắc người dùng kiểm tra dự báo thời tiết và báo cáo thực địa, đồng thời quay đầu ngay khi điều kiện thay đổi xấu đi.
- Không đưa ra lời khuyên y tế vượt quá hướng dẫn cơ bản về bù nước và dinh dưỡng; hãy chỉ dẫn họ tham gia đào tạo sơ cứu và lưu số điện thoại cứu hộ tại địa phương.
FILE:references/time-rules.md
# Quy Tắc Tính Thời Gian

## Quy tắc Naismith (1892)
Dành 1 giờ cho mỗi 5 km trên đường bằng cộng thêm 1 giờ cho mỗi 600 m leo cao (bản gốc là 3 dặm một giờ cộng 1 giờ cho mỗi 2000 ft).
```
moving minutes = distance_km / pace_kmh * 60 + ascent_m / 10
```
Ví dụ: 4.2 km với 380 m leo cao = 50.4 + 38 = 88 phút trước khi áp dụng các hệ số điều chỉnh.

## Các hiệu chỉnh của Langmuir khi xuống dốc
Quy tắc Naismith coi việc xuống dốc giống như đi trên đường bằng. Langmuir đã tinh chỉnh lại như sau:
- dốc xuống thoải, từ 5 đến 12 độ (khoảng 9 đến 21 %): trừ đi 10 phút cho mỗi 300 m xuống dốc
- dốc xuống gắt, trên 12 độ: cộng thêm 10 phút cho mỗi 300 m xuống dốc
- dưới 5 độ: không thay đổi
Kịch bản ước tính góc xuống dốc từ độ cao giảm xuống và tỷ lệ quãng đường đi xuống trong chặng đó. Kịch bản không bao giờ để thời gian đi một chặng giảm xuống thấp hơn một nửa thời gian đi trên đường bằng của chặng đó.

## Các hệ số nhân được kịch bản sử dụng
| Hệ số | Giá trị | Khi nào áp dụng |
|---|---|---|
| Terrain road | 0.9 | Đường trải nhựa hoặc đường lâm nghiệp |
| Terrain path | 1.0 | Đường mòn đi bộ tốt |
| Terrain rough | 1.25 | Đường mòn nhiều đá, rễ cây, đất đá rời rạc hoặc lầy lội |
| Terrain scramble | 1.6 | Cần dùng tay bám, các bậc đá chênh vênh |
| Terrain snow | 1.5 | Tuyết mềm hoặc tuyết cũ chưa cần dùng đinh giày (crampon) |
| Terrain bushwhack | 1.6 | Không có đường mòn, phải vạch cây cối rậm rạp |
| Fitness (Thể lực) | 0.85 / 1.0 / 1.2 / 1.4 | Nhanh và khỏe / trung bình / thong thả hoặc nhóm hỗn hợp / có trẻ nhỏ |
| Pack (Ba lô) | +2 % mỗi kg vượt quá 10 kg | Đi qua đêm hoặc mang vác nặng |
| Breaks (Nghỉ giải lao) | 10 phút mỗi giờ (mặc định) | Dùng 15 đến 20 phút cho các chuyến đi chụp ảnh, gia đình, nhóm đông người |

Hệ số địa hình được nhân cho toàn bộ chặng, bao gồm cả thời gian leo dốc.

## Hiệu chuẩn (Calibrating)
Sau chặng đầu tiên, hãy lấy thời gian thực tế chia cho thời gian dự kiến. Nếu nhóm mất 1 giờ 50 phút cho một chặng dự kiến 1 giờ 37 phút, hệ số chênh lệch là 1.13: hãy chạy lại kịch bản với tham số `--fitness` nhân với hệ số đó và kiểm tra lại giờ kết thúc. Các nhóm luôn di chuyển theo tốc độ của người chậm nhất; hãy lập kế hoạch dựa theo người đó.

## Các quy tắc khác bạn có thể bắt gặp
- Hiệu chỉnh Tranter (Tranter's corrections): bảng tra cứu thể lực và độ mệt mỏi áp dụng thêm trên quy tắc Naismith, được dùng cho những ngày leo núi dài.
- Hàm đi bộ đường dài của Tobler (Tobler's hiking function): tốc độ = 6 * exp(-3.5 * |slope + 0.05|) km/h, được sử dụng trong các công cụ GIS; hàm này cho ra tổng thời gian tương tự trên các tuyến đường hỗn hợp.

## Thời điểm bắt buộc quay đầu (Turnaround time)
Đối với tuyến đường đi và về cùng một lối (out-and-back) hoặc tuyến đường có lối thoát rút lui (bail-out), hãy đặt ra một thời điểm quay đầu cố định: thời gian muộn nhất bạn có thể rời khỏi điểm xa nhất mà vẫn quay về kịp lúc còn một giờ ánh sáng ban ngày. Ví dụ: mặt trời lặn lúc 17:20, giữ dự phòng 60 phút, lượt về mất 3 giờ 10 phút -> bắt buộc phải quay đầu trước 13:10 dù bạn đang ở bất kỳ đâu.
FILE:references/water-food-and-safety.md
# Nước Uống, Thức Ăn và An Toàn

## Tốc độ uống nước được kịch bản sử dụng
| Nhiệt độ | Số lít mỗi giờ (tính trên tổng thời gian) |
|---|---|
| dưới 15 C | 0.4 |
| 15 đến 24 C | 0.5 |
| 25 đến 29 C | 0.75 |
| từ 30 C trở lên | 1.0 |
Cộng thêm 0.1 L cho mỗi 100 m leo cao, vì việc leo dốc khiến bạn đổ mồ hôi nhiều hơn. Nhu cầu thực tế rất khác nhau giữa mỗi người; những người ra nhiều mồ hôi, trẻ em và người ở độ cao lớn có thể cần nhiều nước hơn. Hãy uống từng ngụm nhỏ thường xuyên thay vì uống thật nhiều cùng một lúc, và bổ sung chất điện giải (viên muối, bột pha nước uống hoặc đồ ăn nhẹ có vị mặn) vào những ngày nắng nóng hoặc khi uống nhiều hơn khoảng 3 L nước.

## Lập kế hoạch mang nước
- Điểm xuất phát và mọi chặng được đánh dấu `water_at_end = yes` là các điểm tiếp nước.
- Lượng nước cần mang (Carry) = lượng nước lớn nhất cần dùng giữa hai điểm tiếp nước cộng với 0.5 L dự phòng.
- Mang nhiều hơn 3 L (3 kg) là khá nặng; các phương án xử lý bao gồm giấu sẵn nước dự trữ trên đường, chọn tuyến đường đi qua trạm nghỉ hoặc suối nước, hoặc chuyển đoạn leo dốc nóng bức nhất sang sáng sớm.
- Hãy xác nhận chắc chắn rằng các con suối và trạm nghỉ thực sự có nước vào thời điểm đó trong năm (nhiều trạm nghỉ đóng cửa vào cuối mùa thu; các con suối thường cạn khô vào cuối mùa hè).

## Xử lý nước
Xử lý tất cả các nguồn nước tự nhiên: dùng bộ lọc sợi rỗng (loại bỏ vi khuẩn và động vật nguyên sinh), viên nén chlorine dioxide (diệt được cả vi-rút, cần chờ đủ thời gian tác dụng, thường là 30 phút, và lên đến 4 giờ đối với Cryptosporidium), bút chiếu tia UV cho nước trong, hoặc đun sôi trong 1 phút (3 phút nếu ở độ cao trên 2000 m). Hãy lọc nước đục qua một lớp vải trước khi xử lý.

## Thức ăn
Khoảng 200 đến 300 kcal mỗi giờ khi đang di chuyển sẽ giúp duy trì năng lượng ổn định trong một ngày dài: các loại hạt, thanh năng lượng, trái cây sấy khô, phô mai, bánh mì kẹp. Kịch bản sử dụng mức 250 kcal cho mỗi giờ trên tổng thời gian. Hãy đóng gói dư ra một phần đồ ăn nhẹ cho mỗi người làm nguồn dự phòng khẩn cấp.

## Ánh sáng ban ngày
- Tra cứu giờ mặt trời lặn cho đúng địa điểm và ngày cụ thể (qua ứng dụng thời tiết hoặc thiên văn). Ở vùng núi, ánh nắng mặt trời sẽ khuất khỏi các thung lũng và các sườn dốc hướng đông sớm hơn so với giờ mặt trời lặn chính thức.
- Chạng vạng dân dụng (civil twilight) cung cấp khoảng 20 đến 40 phút ánh sáng có thể nhìn đường sau khi mặt trời lặn ở các vùng vĩ độ trung bình, và ngắn hơn ở vùng nhiệt đới. Tuyệt đối không lập kế hoạch dựa vào khoảng thời gian này.
- Luôn giữ 60 phút ánh sáng ban ngày dự phòng (giá trị `--margin` mặc định). Mọi ba lô đều phải trang bị một đèn đội đầu có pin đã sạc đầy.

## Danh sách kiểm tra an toàn
- Đã kiểm tra dự báo thời tiết vào tối hôm trước và sáng ngày khởi hành (giông bão, sức gió trên sống núi, độ cao đóng băng).
- Đã gửi lại kế hoạch tuyến đường, giờ xuất phát, thời điểm quay đầu và giờ về dự kiến cho một người ở nhà, kèm theo thông tin cần gọi cho ai và vào lúc nào.
- Đã tải bản đồ ngoại tuyến (offline) trên điện thoại, kèm theo sạc dự phòng; mang theo bản đồ giấy và la bàn đối với các tuyến đường hẻo lánh.
- Trang phục mặc nhiều lớp (layers) và áo khoác chống thấm nước, mũ và găng tay khi đi phía trên đường giới hạn cây gỗ (tree line) ngay cả vào mùa hè, cùng đồ chống nắng.
- Bộ sơ cứu nhỏ gọn, băng dán chống phồng rộp, chăn cứu sinh khẩn cấp, còi báo hiệu.
- Nắm rõ số điện thoại khẩn cấp tại địa phương (112 ở Châu Âu, 911 ở Bắc Mỹ) và quy trình gọi cứu hộ đường núi.
- Quy tắc bất di bất dịch: cả nhóm luôn đi cùng nhau và phải quay đầu khi đến giờ bắt buộc quay đầu, ngay khi thấy tia chớp đầu tiên, hoặc khi có bất kỳ ai cảm thấy không khỏe.
FILE:templates/hike-plan.md
# Kế hoạch đi bộ đường dài: <tên tuyến đường>, <ngày>

**Nhóm:** <tên / số lượng thành viên>   **Trưởng nhóm:** <tên, số điện thoại>
**Tuyến đường:** <vòng lặp 22.2 km, +1170 m / -1150 m, liên kết bản đồ>
**Xuất phát:** <08:00 tại bãi đỗ xe Eagle Ridge>   **Dự kiến kết thúc:** <16:19>   **Mặt trời lặn:** <17:20>
**Thời điểm bắt buộc quay đầu:** <13:00 tại đỉnh núi, bất kể tình huống nào>
**Thời hạn báo động muộn nhất cho người liên hệ ở nhà:** <19:00>

## Lịch trình
| Chặng | km | Lên / xuống m | Địa hình | Giờ bắt đầu dự kiến | Giờ kết thúc dự kiến | Tiếp nước |
|---|---|---|---|---|---|---|
| <Bãi đỗ xe đến Pine Saddle> | <4.2> | <+380 / -20> | <path> | <08:00> | <09:53> | <không> |

Các thiết lập đã dùng: <tốc độ 5 km/h, thể lực 1.1, nghỉ 10 phút/giờ, 24 C>. Kiểm tra lại sau chặng đầu tiên và tính lại tỷ lệ.

## Nước uống và thức ăn
- Mang theo từ lúc xuất phát: <4.4 L mỗi người> (không có điểm tiếp nước cho đến <Spring Hut>)
- Tiếp nước tại: <vòi nước ở Spring Hut (mở cửa đến hết tháng 10?), xử lý nước suối>
- Đồ ăn nhẹ: <2100 kcal mỗi người> + một phần dự phòng
- Chất điện giải: <có / không>

## Các phương án rút lui (Bail-out options)
- <Sau Pine Saddle: đi theo đường lâm nghiệp quay lại bãi đỗ xe, 3.5 km, 1 giờ>
- <Bỏ qua đoạn băng qua sống núi: đi xuống theo đường mòn phía bắc từ đỉnh núi>

## Trang bị mang theo (Kit)
- <đèn đội đầu, quần áo nhiều lớp, áo chống thấm, bản đồ ngoại tuyến + sạc dự phòng, bộ sơ cứu, còi, bộ lọc nước hoặc viên khử trùng>

## Thời tiết và điều kiện thực địa
- Dự báo: <đã kiểm tra vào ... : trời khô ráo, 24 C, gió 20 km/h trên sống núi>
- Ghi chú: <đoạn leo bám đá bị ướt sau cơn mưa; tránh đi nếu trời ướt>

## Khẩn cấp
- Số điện thoại khẩn cấp: <112>   Cứu hộ đường núi: <...>
- Người liên hệ ở nhà: <tên, số điện thoại>: nếu không nhận được tin nhắn trước <19:00>, hãy gọi số <số điện thoại> kèm theo bản kế hoạch này.
FILE:examples/eagle-ridge-loop.csv
leg,distance_km,ascent_m,descent_m,terrain,water_at_end
Car park to Pine Saddle,4.2,380,20,path,no
Pine Saddle to Eagle Ridge summit,3.1,520,40,rough,no
Eagle Ridge traverse,1.6,120,150,scramble,no
Ridge down to Spring Hut,3.8,30,560,path,yes
Spring Hut to Blue Lake,4.5,80,210,path,no
Blue Lake back to car park,5.0,40,170,road,yes
FILE:scripts/hike_plan.py
#!/usr/bin/env python3
"""Hiking route time and water planner (Python 3 standard library only).

Reads a CSV of route legs and estimates moving time per leg with Naismith's rule
(5 km/h plus 1 hour per 600 m of ascent) and Langmuir's descent corrections,
adjusted for terrain, fitness and pack weight, then adds breaks, gives clock
times for every leg, checks the finish against sunset, and works out how much
water to carry between refill points and how much food to pack.

CSV columns (header required; ; or , separated):
  leg, distance_km, ascent_m, descent_m, terrain, water_at_end
terrain: road | path | rough | scramble | snow | bushwhack   water_at_end: yes/no

Usage:
  python3 hike_plan.py route.csv --start 08:30 --sunset 17:10 --temp 24
  python3 hike_plan.py route.csv --start 07:00 --fitness 1.2 --pack-kg 14 --json
  python3 hike_plan.py --self-test
Exit codes: 0 = plan fine, 1 = HIGH findings (finish after sunset), 2 = bad input.
"""
import argparse, csv, io, json, math, sys

TERRAIN = {"road": 0.9, "path": 1.0, "trail": 1.0, "rough": 1.25, "scramble": 1.6, "snow": 1.5, "bushwhack": 1.6}
REQUIRED = ["leg", "distance_km", "ascent_m", "descent_m", "terrain", "water_at_end"]
SEV = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}


class InputError(Exception):
    pass


def num(v, field, row):
    try:
        x = float(str(v).strip().replace(",", "."))
    except ValueError:
        raise InputError(f"row {row}: {field} '{v}' is not a number")
    if x < 0:
        raise InputError(f"row {row}: {field} cannot be negative")
    return x


def hm(s):
    try:
        h, m = s.strip().split(":")
        h, m = int(h), int(m)
        assert 0 <= h < 24 and 0 <= m < 60
        return h * 60 + m
    except Exception:
        raise InputError(f"time '{s}' must be HH:MM")


def clock(mins):
    mins = int(round(mins))
    day, rem = divmod(mins, 1440)
    return f"{rem // 60:02d}:{rem % 60:02d}" + (f" (+{day}d)" if day else "")


def dur(mins):
    mins = int(round(mins))
    return f"{mins // 60}h{mins % 60:02d}"


def read_legs(text):
    sample = text[:2000]
    delim = ";" if sample.count(";") > sample.count(",") else ","
    rd = csv.DictReader(io.StringIO(text), delimiter=delim)
    if not rd.fieldnames:
        raise InputError("empty CSV")
    fields = [f.strip().lower() for f in rd.fieldnames]
    missing = [c for c in REQUIRED if c not in fields]
    if missing:
        raise InputError("missing columns: " + ", ".join(missing))
    legs = []
    for i, raw in enumerate(rd, start=2):
        r = {k.strip().lower(): (v or "").strip() for k, v in raw.items() if k}
        if not any(r.values()):
            continue
        t = r["terrain"].lower() or "path"
        if t not in TERRAIN:
            raise InputError(f"row {i}: terrain '{t}' must be one of {', '.join(TERRAIN)}")
        w = r["water_at_end"].lower()
        if w not in ("yes", "no", "y", "n", "1", "0", "true", "false", ""):
            raise InputError(f"row {i}: water_at_end must be yes or no")
        legs.append({"leg": r["leg"] or f"Leg {len(legs) + 1}",
                     "distance_km": num(r["distance_km"], "distance_km", i),
                     "ascent_m": num(r["ascent_m"], "ascent_m", i),
                     "descent_m": num(r["descent_m"], "descent_m", i),
                     "terrain": t, "water_at_end": w in ("yes", "y", "1", "true")})
    if not legs:
        raise InputError("no legs in CSV")
    return legs


def water_rate(temp_c):
    """Litres per hour of total time, before the ascent extra."""
    if temp_c < 15:
        return 0.4
    if temp_c < 25:
        return 0.5
    if temp_c < 30:
        return 0.75
    return 1.0


def leg_minutes(leg, pace_kmh):
    d, up, down = leg["distance_km"], leg["ascent_m"], leg["descent_m"]
    flat = d / pace_kmh * 60
    climb = up / 10.0  # Naismith: 60 min per 600 m
    descent_adj = 0.0
    steep = False
    if down > 0 and d > 0:
        horiz = d * 1000 * (down / (up + down))  # share of the leg spent descending
        angle = math.degrees(math.atan(down / horiz)) if horiz > 0 else 90
        if 5 <= angle <= 12:
            descent_adj = -down / 300 * 10   # Langmuir: gentle descent is faster
        elif angle > 12:
            descent_adj = down / 300 * 10    # steep descent is slower
        steep = angle > 14
    if up > 0 and d > 0:
        horiz_up = d * 1000 * (up / (up + down))
        steep = steep or math.degrees(math.atan(up / horiz_up)) > 14  # about 25 %
    return max(flat + climb + descent_adj, flat * 0.5), steep


def plan(legs, start, sunset=None, pace=5.0, fitness=1.0, pack_kg=8.0, break_min=10.0, temp=18.0, margin=60):
    if pace <= 0 or fitness <= 0:
        raise InputError("pace and fitness must be positive")
    pack_factor = 1.0 + max(0.0, pack_kg - 10) * 0.02  # +2 % per kg above 10 kg
    rate = water_rate(temp)
    t = start
    rows, findings = [], []
    stretch, stretches, stretch_legs = 0.0, [], []
    for leg in legs:
        base, steep = leg_minutes(leg, pace)
        moving = base * TERRAIN[leg["terrain"]] * fitness * pack_factor
        total = moving * (1 + break_min / 60)
        water = total / 60 * rate + leg["ascent_m"] / 100 * 0.1
        t_start, t = t, t + total
        rows.append({**leg, "moving_min": round(moving), "with_breaks_min": round(total),
                     "start": clock(t_start), "end": clock(t), "end_min": t, "water_l": round(water, 2), "steep": steep})
        stretch += water
        stretch_legs.append(leg["leg"])
        if leg["water_at_end"]:
            stretches.append((stretch, stretch_legs)); stretch, stretch_legs = 0.0, []
        if steep:
            findings.append(("LOW", "STEEP_LEG", f"{leg['leg']}: average gradient over 25 %; expect slower going than the formula and take care on the descent"))
    if stretch_legs:
        stretches.append((stretch, stretch_legs))
    moving_total = sum(r["moving_min"] for r in rows)
    total = t - start
    carry = max(s for s, _ in stretches) + 0.5
    for s, names in stretches:
        if s + 0.5 > 3.0:
            findings.append(("MEDIUM", "LONG_DRY_STRETCH", f"{' -> '.join(names)}: {s + 0.5:.1f} L to carry with no refill; add a refill, cache water or start earlier in the cool"))
    summary = {
        "distance_km": round(sum(l["distance_km"] for l in legs), 1),
        "ascent_m": round(sum(l["ascent_m"] for l in legs)),
        "descent_m": round(sum(l["descent_m"] for l in legs)),
        "moving_min": round(moving_total), "total_min": round(total),
        "start": clock(start), "finish": clock(t),
        "water_total_l": round(sum(r["water_l"] for r in rows), 1),
        "carry_max_l": round(carry, 1),
        "food_kcal": int(round(total / 60 * 250, -1)),
        "water_rate_l_per_h": rate, "pack_factor": round(pack_factor, 2),
    }
    if sunset is not None:
        left = sunset - t
        summary["sunset"] = clock(sunset)
        summary["minutes_before_sunset"] = round(left)
        summary["latest_start"] = clock(sunset - margin - total)
        if left < 0:
            findings.append(("HIGH", "AFTER_DARK", f"finish {clock(t)} is {dur(-left)} after sunset {clock(sunset)}; start by {summary['latest_start']}, shorten the route or plan a bail-out"))
        elif left < margin:
            findings.append(("MEDIUM", "SMALL_MARGIN", f"finish {clock(t)} leaves only {round(left)} min before sunset (target {margin}); start by {summary['latest_start']} and carry a headlamp"))
        for r in rows:
            if r["terrain"] in ("scramble", "snow") and r["end_min"] > sunset - 120:
                findings.append(("MEDIUM", "HARD_TERRAIN_LATE", f"{r['leg']} ({r['terrain']}) ends at {r['end']}, within 2 h of sunset; tired legs and fading light on hard ground"))
    if moving_total > 8 * 60:
        findings.append(("LOW", "LONG_DAY", f"{dur(moving_total)} moving time; check that everyone has done a day this long recently"))
    if temp >= 28 and any(l["ascent_m"] >= 300 for l in legs):
        findings.append(("MEDIUM", "HEAT", f"{temp:g} C with big climbs: start at first light, rest in shade, electrolytes with the water"))
    findings.sort(key=lambda f: SEV[f[0]])
    for r in rows:
        r.pop("end_min")
    return {"legs": rows, "summary": summary, "stretches": [{"legs": n, "litres": round(s + 0.5, 1)} for s, n in stretches],
            "findings": [{"severity": a, "code": b, "message": c} for a, b, c in findings]}


def to_markdown(p, args):
    s = p["summary"]
    out = ["# Hike plan", "",
           f"Settings: pace {args.pace:g} km/h, fitness x{args.fitness:g}, pack {args.pack_kg:g} kg (x{s['pack_factor']}), breaks {args.break_min:g} min per hour, {args.temp:g} C",
           "",
           f"Route: {s['distance_km']} km, +{s['ascent_m']} m / -{s['descent_m']} m; moving {dur(s['moving_min'])}, with breaks {dur(s['total_min'])}",
           f"Start {s['start']}, finish about {s['finish']}" + (f"; sunset {s['sunset']}, " + (f"{s['minutes_before_sunset']} min to spare" if s['minutes_before_sunset'] >= 0 else f"{dur(-s['minutes_before_sunset'])} AFTER sunset") + f"; latest sensible start {s['latest_start']}" if "sunset" in s else ""),
           "", "| Leg | km | Up m | Down m | Terrain | Moving | With breaks | Start | End | Water L | Refill at end |",
           "|---|---|---|---|---|---|---|---|---|---|---|"]
    for r in p["legs"]:
        out.append(f"| {r['leg']} | {r['distance_km']:g} | {r['ascent_m']:g} | {r['descent_m']:g} | {r['terrain']} | {dur(r['moving_min'])} | "
                   f"{dur(r['with_breaks_min'])} | {r['start']} | {r['end']} | {r['water_l']:.1f} | {'yes' if r['water_at_end'] else 'no'} |")
    out += ["", "## Water and food",
            f"- Drinking rate {s['water_rate_l_per_h']} L/h at this temperature plus 0.1 L per 100 m of climbing; total about {s['water_total_l']} L",
            f"- Carry at most {s['carry_max_l']} L (largest stretch between refills, incl. 0.5 L reserve); treat stream water"]
    for st in p["stretches"]:
        out.append(f"  - {' -> '.join(st['legs'])}: {st['litres']} L")
    out.append(f"- Food: about {s['food_kcal']} kcal of snacks (about 250 kcal per hour on the move), plus a spare")
    out += ["", "## Findings"]
    out += [f"- {f['severity']} {f['code']}: {f['message']}" for f in p["findings"]] or ["- none"]
    out += ["", "Estimates only: check them against your group's real pace on the first leg and adjust."]
    return "\n".join(out)


def self_test():
    res = []

    def check(name, cond):
        res.append(cond)
        print(("PASS " if cond else "FAIL ") + name)

    def L(d, up, down, terrain="path", water="no", name="x"):
        return {"leg": name, "distance_km": d, "ascent_m": up, "descent_m": down, "terrain": terrain, "water_at_end": water == "yes"}

    check("flat 10 km at 5 km/h = 120 min", round(leg_minutes(L(10, 0, 0), 5)[0]) == 120)
    check("Naismith 600 m climb adds 60 min", round(leg_minutes(L(5, 600, 0), 5)[0]) == 120)
    g = leg_minutes(L(6, 0, 900), 5)[0]  # angle ~8.5 deg: gentle
    check("gentle descent is faster (Langmuir)", round(g) == 72 - 30)
    st = leg_minutes(L(2, 0, 600), 5)  # ~16.7 deg: steep
    check("steep descent is slower and flagged", round(st[0]) == 24 + 20 and st[1])
    check("steep ascent flagged", leg_minutes(L(1, 400, 0), 5)[1])
    check("descent never below half the flat time", leg_minutes(L(10, 0, 1500), 5)[0] >= 60)
    p = plan([L(10, 0, 0)], hm("08:00"), break_min=0)
    check("finish time no breaks", p["summary"]["finish"] == "10:00")
    p = plan([L(10, 0, 0)], hm("08:00"), break_min=10)
    check("10 min break per hour", p["summary"]["total_min"] == 140)
    check("terrain multiplier", plan([L(10, 0, 0, "scramble")], 0, break_min=0)["summary"]["moving_min"] == 192)
    check("fitness multiplier", plan([L(10, 0, 0)], 0, fitness=1.2, break_min=0)["summary"]["moving_min"] == 144)
    check("pack over 10 kg slows", plan([L(10, 0, 0)], 0, pack_kg=15, break_min=0)["summary"]["moving_min"] == 132)
    p = plan([L(10, 0, 0)], hm("15:00"), sunset=hm("16:30"), break_min=0)
    check("AFTER_DARK HIGH", p["findings"][0]["code"] == "AFTER_DARK" and p["findings"][0]["severity"] == "HIGH")
    check("latest start", p["summary"]["latest_start"] == "13:30")
    p = plan([L(10, 0, 0)], hm("14:00"), sunset=hm("16:30"), break_min=0)
    check("SMALL_MARGIN", [f["code"] for f in p["findings"]] == ["SMALL_MARGIN"])
    check("no finding with time to spare", plan([L(10, 0, 0)], hm("08:00"), sunset=hm("18:00"))["findings"] == [])
    check("HARD_TERRAIN_LATE", any(f["code"] == "HARD_TERRAIN_LATE" for f in
          plan([L(3, 0, 0, "scramble")], hm("13:00"), sunset=hm("15:00"))["findings"]))
    check("water rate by temperature", [water_rate(t) for t in (10, 20, 27, 33)] == [0.4, 0.5, 0.75, 1.0])
    p = plan([L(10, 0, 0, water="yes"), L(10, 0, 0)], 0, temp=20, break_min=0)
    check("water per leg", p["legs"][0]["water_l"] == 1.0)
    check("carry = largest stretch + reserve", p["summary"]["carry_max_l"] == 1.5)
    p = plan([L(10, 500, 0), L(10, 0, 500)], 0, temp=31, break_min=0)
    check("LONG_DRY_STRETCH and HEAT", {"LONG_DRY_STRETCH", "HEAT"} <= {f["code"] for f in p["findings"]})
    check("LONG_DAY", any(f["code"] == "LONG_DAY" for f in plan([L(45, 0, 0)], 0)["findings"]))
    check("food kcal", plan([L(10, 0, 0)], 0, break_min=0)["summary"]["food_kcal"] == 500)
    check("clock wraps past midnight", clock(1500) == "01:00 (+1d)")
    legs = read_legs("leg;distance_km;ascent_m;descent_m;terrain;water_at_end\nA;3,5;200;0;Path;yes\n")
    check("semicolon CSV + decimal comma", legs[0]["distance_km"] == 3.5 and legs[0]["water_at_end"])
    for bad, why in [("leg,distance_km\nA,1\n", "missing columns"),
                     ("leg,distance_km,ascent_m,descent_m,terrain,water_at_end\nA,x,0,0,path,no\n", "non-number"),
                     ("leg,distance_km,ascent_m,descent_m,terrain,water_at_end\nA,1,-5,0,path,no\n", "negative"),
                     ("leg,distance_km,ascent_m,descent_m,terrain,water_at_end\nA,1,0,0,lava,no\n", "unknown terrain")]:
        try:
            read_legs(bad); check("rejects " + why, False)
        except InputError:
            check("rejects " + why, True)
    try:
        hm("25:00"); check("rejects bad time", False)
    except InputError:
        check("rejects bad time", True)
    passed = sum(res)
    print(f"{passed}/{len(res)} passed")
    return 0 if passed == len(res) else 1


def main():
    ap = argparse.ArgumentParser(description="Hiking route time and water planner")
    ap.add_argument("csv", nargs="?", help="legs CSV")
    ap.add_argument("--start", help="start time HH:MM")
    ap.add_argument("--sunset", help="sunset time HH:MM")
    ap.add_argument("--pace", type=float, default=5.0, help="flat walking speed km/h (default 5)")
    ap.add_argument("--fitness", type=float, default=1.0, help="time multiplier: 0.85 fast, 1.0 average, 1.2 relaxed, 1.4 with young kids")
    ap.add_argument("--pack-kg", type=float, default=8.0, help="pack weight; +2%% time per kg above 10")
    ap.add_argument("--break-min", type=float, default=10.0, help="break minutes per hour of walking (default 10)")
    ap.add_argument("--temp", type=float, default=18.0, help="expected daytime temperature C")
    ap.add_argument("--margin", type=int, default=60, help="minutes of daylight to keep in hand (default 60)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    if not a.csv or not a.start:
        ap.error("give a CSV and --start, or --self-test")
    try:
        with open(a.csv, encoding="utf-8-sig") as fh:
            legs = read_legs(fh.read())
        p = plan(legs, hm(a.start), hm(a.sunset) if a.sunset else None, a.pace, a.fitness, a.pack_kg, a.break_min, a.temp, a.margin)
    except (OSError, InputError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(p, indent=2) if a.json else to_markdown(p, a))
    return 1 if any(f["severity"] == "HIGH" for f in p["findings"]) else 0


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

Hãy đóng vai Chuyên Gia Khắc Phục Sự Cố Sức Khỏe Bể Cá Tại Nhà. Bạn giúp những người chơi cá cảnh tìm ra nguyên nhân vì sao bể cá nước ngọt hoặc đàn cá của họ đang gặp vấn đề và hướng dẫn họ đưa bể cá trở lại trạng thái ổn định, khỏe mạnh. Bạn tư duy như một người nuôi cá dày dạn kinh nghiệm kết hợp với một bác sĩ thú y cẩn trọng: luôn bắt đầu từ chất lượng nước trước khi đổ lỗi cho mầm bệnh, hỏi số liệu đo kiểm cụ thể thay vì phỏng đoán, giải thích mọi thuật ngữ ngay lần đầu tiên sử dụng, và luôn tách biệt rõ giữa nguyên nhân có khả năng cao với nguyên nhân chỉ mang tính giả thuyết. Bạn không bao giờ khuyên châm thuốc một cách mù quáng, và luôn nói rõ khi nào vấn đề cần đến bác sĩ thú y thủy sản chuyên khoa hoặc cửa hàng cá cảnh địa phương có thiết bị kiểm tra chuyên dụng.

Thông tin bể cá của tôi:
- Kích thước và tuổi đời của bể: about 100 liters, set up 7 weeks ago
- Các loài cá và sinh vật khác: 6 neon tetras, 2 platies, 1 bristlenose pleco, a few nerite snails
- Những biểu hiện tôi đang thấy: cloudy white water, two tetras gasping near the surface, one platy with clamped fins
- Thời điểm bắt đầu xuất hiện: 4 days ago, right after I added the platies
- Kết quả đo kiểm nước (nếu có): not tested yet, I have strips but no liquid kit
- Hệ thống lọc, sưởi và đèn chiếu sáng: hang-on-back filter, 26 C heater, LED light on 10 hours a day
- Thói quen bảo dưỡng định kỳ: 25 percent water change every two weeks with dechlorinator, filter sponge rinsed under the tap
- Chế độ cho ăn: flakes twice a day, algae wafer every other night
- Cây thủy sinh và đồ trang trí: a few live plants, driftwood, gravel
- Những thay đổi gần đây: new fish, moved the tank closer to a window

Trước tiên, trong một tin nhắn ngắn gọn, hãy hỏi tôi bất kỳ thông tin quan trọng nào còn thiếu: chỉ số đo chính xác của amoniac (ammonia), nitrit (nitrite), nitrat (nitrate), pH và nhiệt độ (cùng GH hoặc KH nếu tôi có), có con cá nào đã chết chưa và chết nhanh như thế nào, mô tả cận cảnh hoặc hình ảnh về bất kỳ đốm lạ, mảng nấm bông, vết thương hoặc bụng sưng phồng nào, cá mới mua về có được cách ly kiểm dịch (quarantine) hay không, và chỉ số nước máy tại nhà tôi là bao nhiêu. Nếu có bất kỳ dấu hiệu nào giống tình huống khẩn cấp (amoniac hoặc nitrit cao, cá đớp khí trên mặt nước, hỏng sưởi), hãy đưa ra các bước xử lý khẩn cấp ngay lập tức rồi mới đặt câu hỏi sau.

Sau đó, hãy hướng dẫn tôi qua các phần sau:

1. **Tóm Tắt Phân Loại Khẩn Cấp (Triage Summary)**: kết luận ngắn gọn (ổn định, theo dõi sát, cần xử lý ngay hôm nay, khẩn cấp) cùng hai hoặc ba nguyên nhân có khả năng cao nhất theo thứ tự ưu tiên, và một việc duy nhất tôi cần làm ngay trong một giờ tới.

2. **Thuật Ngữ Bể Cá Bạn Sẽ Gặp**: bảng thuật ngữ ngắn gọn gồm tên thuật ngữ và giải thích dễ hiểu: chu trình nitơ (nitrogen cycle), vi sinh có lợi (beneficial bacteria), amoniac (ammonia), nitrit (nitrite), nitrat (nitrate), hội chứng bể mới (new tank syndrome), chạy lọc tạo vi sinh (cycling), tải sinh học (bioload), dung dịch khử clo (dechlorinator), GH, KH, biến động pH (pH swing), bể cách ly (quarantine tank) và bùng phát vi khuẩn làm đục nước (bacterial bloom).

3. **Bảng Giải Mã Triệu Chứng**: bảng liệt kê mọi triệu chứng tôi đã mô tả, với các cột: triệu chứng, ý nghĩa thông thường, khả năng nghiêm trọng hơn, phép thử hoặc quan sát nào giúp phân biệt chúng, và mức độ khẩn cấp. Bao gồm cả hình thức bên ngoài của nước (đục trắng, xanh lá, nâu, vàng, nổi bọt, có mùi hôi) và hành vi của cá (đớp khí, cụp vây, ẩn nấp, cọ mình vào đồ vật, lờ đờ, bỏ ăn, nổi đốm, mọc nấm bông, rách vây, chướng bụng).

4. **Kiểm Tra Chất Lượng Nước**: ý nghĩa của từng kết quả đo, ngưỡng an toàn cho các loài cá của tôi, cách đọc que thử (strips) so với bộ test dung dịch nhỏ giọt (liquid kits), tại sao cần kiểm tra cả nước máy lẫn nước trong bể, và quy tắc rõ ràng về việc cần làm ở từng mức chỉ số (ví dụ: bất kỳ chỉ số amoniac hoặc nitrit nào lớn hơn 0 trong một bể đã ổn định đều đồng nghĩa với việc phải thay nước ngay hôm nay).

5. **Trạng Thái Chu Trình Vi Sinh (Cycle Status)**: đánh giá xem bể của tôi đã hoàn tất chu trình vi sinh hay chưa dựa trên tuổi bể, mật độ nuôi và kết quả test nước; giải thích việc thả thêm cá mới và rửa vật liệu lọc bằng nước máy có thể làm sập hệ vi sinh có lợi như thế nào, cũng như cách bảo vệ hoặc gây dựng lại hệ vi sinh mà không làm chết cá.

6. **Kế Hoạch Hành Động Trong 7 Ngày Tới**: bảng lịch trình từng ngày gồm các cột: ngày, hành động cần làm, các chỉ số cần đo, dấu hiệu cần theo dõi, và kết quả nào cho thấy phương pháp đang phát huy tác dụng. Bao gồm tỷ lệ thay nước an toàn và cách cân bằng nhiệt độ nước mới, điều chỉnh lượng thức ăn, chăm sóc bộ lọc, và khi nào nên ngừng can thiệp thêm.

7. **Bệnh Lý Hay Vấn Đề Nguồn Nước?**: cách phân biệt vấn đề môi trường nước với nhiễm trùng hoặc ký sinh trùng, các bệnh phổ biến khớp với triệu chứng của tôi (ví dụ: bệnh nấm trắng ich, thối vây, columnaris hoặc bệnh nhung velvet), và khi nào việc dùng thuốc là hợp lý. Không bao giờ nêu tên thuốc và liều lượng mà không dặn tôi tuân thủ chính xác hướng dẫn trên nhãn sản phẩm, tháo than hoạt tính khỏi bộ lọc nếu nhãn thuốc yêu cầu, và kiểm tra xem thuốc có an toàn cho ốc, tép, cây thủy sinh và các loài cá da trơn không vảy như cá dọn bể (pleco) của tôi hay không.

8. **Kiểm Tra Mật Độ Nuôi và Độ Tương Thích**: đánh giá xem các loài cá của tôi có phù hợp với kích thước bể, nhiệt độ và độ pH khi sống chung hay không, số lượng cá theo đàn tối thiểu, kích thước khi trưởng thành, tải sinh học, và nguy cơ bắt nạt hoặc rỉa vây. Chỉ đề xuất thay đổi nếu điều đó tốt cho đàn cá.

9. **Ánh Sáng, Rêu Tảo và Cây Thủy Sinh**: việc di chuyển bể gần cửa sổ và số giờ bật đèn ảnh hưởng thế nào đến rêu tảo và nhiệt độ nước, lịch bật đèn hợp lý, và những cách đơn giản để giữ cây thủy sinh khỏe mạnh mà không châm quá liều phân nước.

10. **Lịch Chăm Sóc Định Kỳ**: danh sách kiểm tra hàng tuần, hàng tháng và hàng quý gồm công việc, thời gian cần thiết và lý do tại sao mỗi việc lại quan trọng: thay nước, hút cặn nền, rửa vật liệu lọc trong nước cũ rút từ bể, đo kiểm nước, cạo rêu mặt kính, kiểm tra sưởi và nhiệt kế, cắt tỉa cây, và quy trình cách ly đối với cá mới.

11. **Quy Tắc Phòng Ngừa**: tám quy tắc ngắn gọn lẽ ra đã giúp ngăn chặn sự cố hôm nay, được đối chiếu trực tiếp với những gì tôi đã chia sẻ với bạn.

12. **Khi Nào Cần Tìm Sự Trợ Giúp**: các dấu hiệu rõ ràng cần đến bác sĩ thú y thủy sản hoặc cửa hàng cá cảnh giàu kinh nghiệm, cùng những thông tin và mẫu nước cần mang theo.

Quy tắc: luôn hỏi số liệu cụ thể thay vì tự suy đoán; gắn nhãn mọi nguyên nhân là có khả năng cao (likely), có thể xảy ra (possible) hoặc ít khả năng (unlikely); ưu tiên các biện pháp khắc phục nhẹ nhàng, từ từ hơn là những thay đổi lớn đột ngột; không bao giờ gợi ý thả cá hoặc cây thủy sinh ra môi trường tự nhiên; luôn đặt phúc lợi động vật lên hàng đầu; sử dụng ngôn ngữ dễ hiểu, đoạn văn ngắn gọn và bảng biểu ở những chỗ hữu ích. Kết thúc bằng một việc quan trọng nhất mà tôi cần làm ngay hôm nay.

Hãy đóng vai một nhà thiết kế bối cảnh phong cảnh điện ảnh chuyên viết các bản tóm tắt bối cảnh sẵn sàng cho việc tạo ảnh và tạo chuyển động (image-ready và motion-ready). Hãy giúp tôi thiết kế một cảnh quay chủ đạo (hero shot) về một ngôi nhà trang trại bằng đá cổ kính nằm ở cuối những luống hoa oải hương màu tím trải dài tại vùng Provence lúc bình minh. Cảnh quay này trước tiên sẽ được tạo ra dưới dạng một bức ảnh tĩnh và sau đó được tạo chuyển động thành một đoạn video ngắn sử dụng chính bức ảnh đó làm khung hình đầu tiên. Bản tóm tắt của bạn phải làm cho bức ảnh tĩnh giàu các yếu tố có thể chuyển động một cách tự nhiên (các luống hoa oải hương đung đưa trong làn gió nhẹ, sương sớm trôi qua những ngọn đồi, ánh sáng của mặt trời lúc mới mọc từ từ rực lên, những đám mây nhỏ trôi nhẹ, đàn ong bay trên mặt hoa, một hoặc hai chú chim bay ngang bầu trời) đồng thời vẫn giữ cho bố cục sự yên bình, rõ ràng và dễ tạo chuyển động.

Các lựa chọn khởi đầu của tôi:
- Ngôi nhà trang trại: a two-story old stone farmhouse with a terracotta tile roof and pale blue shutters
- Cây cối: one tall dark cypress right beside the house and a lone round oak tree on a grassy rise
- Cánh đồng hoa oải hương: long straight rows of purple lavender with dirt paths between them, converging toward the house
- Phong cảnh: gentle rolling hills fading to blue in the distance
- Thời gian và ánh sáng: sunrise with the sun just above the hills, warm golden light, long shadows, light haze
- Phong cách hình ảnh: photoreal landscape photography, natural colors
- Các từ khóa tâm trạng (Mood words): peaceful, warm, fragrant, timeless

Trước tiên, hãy hỏi tôi trong một tin nhắn ngắn gọn về bất kỳ thông tin nào còn thiếu: vị trí đặt máy quay mà tôi ưa thích (đặt thấp ở cuối một luống hoa oải hương, ngang tầm mắt người đứng trên lối đi, hay hơi nâng cao một chút), ngôi nhà trang trại và cây sồi nên nằm ở phía bên nào của khung hình, mặt trời nên ở đâu, tôi muốn có bao nhiêu sương mù, và bất kỳ yếu tố nào cần tránh (con người, xe hơi, máy kéo, hàng rào, biển báo, những chú chim đòi hỏi chuyển động vỗ cánh phức tạp, chữ viết, logo, hoặc việc sao chép một bức ảnh chụp có thật cụ thể).

Sau đó, hãy lập bản tóm tắt với các phần sau đây:

1. **Tổng quan Bối cảnh (Scene Overview)**: hai hoặc ba câu mô tả địa điểm, thời gian, ánh sáng và cảm xúc của khoảnh khắc đó. Hãy mô tả một khung cảnh Provence tưởng tượng mang đậm tinh thần của vùng đất này, chứ không phải bản sao của một bức ảnh cụ thể hay một trang trại có tên tuổi ngoài đời thực.

2. **Ngôi nhà Trang trại và Cây cối (Farmhouse and Trees)**: vị trí và kích thước của ngôi nhà trang trại trong khung hình, những bức tường đá, mái nhà, cửa chớp, cửa sổ và những bụi cây xung quanh nó, cây bách và cây sồi cùng vị trí chúng đứng, và cách ánh mặt trời ở vị trí thấp chiếu sáng từng chi tiết đó.

3. **Các luống Hoa oải hương và Tiền cảnh (Lavender Rows and Foreground)**: số lượng luống hoa nhìn thấy được, lối đi ở trung tâm, cách các luống hoa hội tụ về phía điểm tụ (vanishing point), màu sắc của những bông hoa dưới ánh nắng và trong bóng râm, cùng kết cấu của những cành hoa gần nhất.

4. **Phong cảnh và Chiều sâu (Landscape and Depth)**: các lớp chiều sâu tính từ thảm hoa oải hương ở tiền cảnh cho đến ngôi nhà trang trại, cây sồi trên gò đất cao, thảm thực vật xanh ở trung cảnh, những ngọn đồi nơi đường chân trời, và cách làn sương mù làm dịu đi từng lớp cảnh vật.

5. **Ánh sáng và Bầu trời (Light and Sky)**: vị trí và độ cao của mặt trời, quầng sáng và sắc ấm trên ống kính xung quanh mặt trời, dải chuyển màu (gradient) của bầu trời, hình dáng và vị trí của những đám mây, chiều dài và hướng của các bóng đổ dọc theo các luống hoa.

6. **Các Chi tiết Hình ảnh Cố định (Fixed Visual Details)**: một danh sách đánh số gồm 8 đến 10 chi tiết bắt buộc phải giữ nguyên giống hệt nhau trong cả bức ảnh tĩnh và trong video (vị trí ngôi nhà trang trại, màu mái nhà và cửa chớp, vị trí cây bách, vị trí cây sồi, hướng của các luống hoa và lối đi trung tâm, vị trí mặt trời, đường chân trời, bố cục đám mây, vị trí máy quay, khung hình).

7. **Sơ đồ Chuyển động (Motion Map)**: một bảng liệt kê mọi yếu tố có thể chuyển động trong video, với các cột: yếu tố, kiểu chuyển động, hướng, tốc độ (rất chậm, chậm, trung bình), và mức độ chuyển động mạnh hay nhẹ. Bao gồm hoa oải hương, làn sương, quầng sáng mặt trời, mây, cây cối, đàn ong hoặc chim chóc, và chuyển động của máy quay. Giữ cho tổng thể chuyển động tinh tế và hợp lý về mặt vật lý, với một hướng gió duy nhất.

8. **Prompt Hạt giống A - Ảnh Tĩnh Chủ đạo (Prompt Seed A - Hero Still Image)**: một prompt tạo ảnh sẵn sàng để sao chép-dán dưới 170 từ cho khung hình ngang rộng tỷ lệ 16:9, có nhắc đến các luống hoa oải hương, ngôi nhà trang trại bằng đá và cảnh bình minh ngay trong câu đầu tiên, kết thúc bằng cụm từ: no people, no text, no logos.

9. **Prompt Hạt giống B - Hoạt cảnh Chuyển đổi từ Ảnh sang Video (Prompt Seed B - Image-to-Video Animation)**: một prompt tạo video sẵn sàng để sao chép-dán dưới 120 từ bắt đầu từ bức ảnh tĩnh chủ đạo làm khung hình đầu tiên, mô tả hoa oải hương đung đưa, làn sương trôi nhẹ, quầng sáng rực lên, những đám mây nhỏ trôi, một chuyển động máy quay tiến vào (push-in) rất chậm dọc theo luống hoa trung tâm trong khoảng 6 giây, và dặn giữ nguyên ngôi nhà trang trại, cây cối, các luống hoa cùng khung hình giống hệt như trong ảnh mà không xuất hiện thêm vật thể mới nào.

Quy tắc: không có người, phương tiện giao thông hay máy móc nông nghiệp; không có chữ viết, biển báo hay logo; không có chuyển động máy quay nhanh hay cắt cảnh; và không có chuyển động nào phá vỡ quy luật vật lý (tất cả cây cối đều nghiêng theo cùng một chiều gió, ngôi nhà và các thân cây lớn không bao giờ dịch chuyển hay biến dạng, mặt trời không nhảy cóc, bóng đổ luôn nhất quán với vị trí mặt trời). Hãy sử dụng các đoạn văn ngắn và danh sách.

---
name: recipe-scaling-and-unit-converter
description: Quy đổi công thức nấu ăn theo khẩu phần, hệ số nhân hoặc kích thước khuôn (vuông, chữ nhật, tròn, khuôn bánh mì gối), chuyển đổi giữa cốc (cup) và thìa chuẩn Mỹ, thể tích hệ mét và gam thông qua bảng khối lượng riêng của nguyên liệu, làm tròn về mức có thể đong đếm được, đồng thời cảnh báo các lưu ý khi làm bánh như trứng lẻ phần thập phân, chất tạo nở ở hệ số nhân lớn, độ dày bột và thời gian nướng khi thay đổi khuôn, định lượng quá nhỏ, gia vị và thời gian nấu. Bao gồm một trình quy đổi bằng thư viện chuẩn Python có hỗ trợ --self-test.
---

# Công cụ Quy đổi Khẩu phần Công thức và Chuyển đổi Đơn vị

Bạn giúp những người nấu ăn tại gia và thợ làm bánh tăng, giảm khối lượng công thức hoặc điều chỉnh cho vừa với một chiếc khuôn khác, bằng chính những đơn vị mà họ thực sự sử dụng. Bạn đưa ra các định lượng mà họ có thể đong đếm được, hiển thị hệ số nhân và các phép chuyển đổi đằng sau đó, đồng thời cảnh báo về những yếu tố không tăng giảm theo tỷ lệ tuyến tính: trứng, chất tạo nở, độ sâu của khuôn, thời gian nướng, gia vị và thời gian nấu.

## Các tệp trong kỹ năng này

- `scripts/scale_recipe.py` - đọc tệp CSV nguyên liệu, quy đổi theo khẩu phần, hệ số nhân hoặc diện tích khuôn, chuyển đổi sang đơn vị chuẩn Mỹ (US), hệ mét hoặc gam, làm tròn về các mức đong đếm trong bếp và liệt kê các lưu ý (chỉ dùng thư viện chuẩn Python 3)
- `references/conversions-and-densities.md` - thể tích và trọng lượng chuẩn Mỹ/hệ mét, số gam trên mỗi cốc (cup) cho khoảng 30 nguyên liệu phổ biến, kích cỡ trứng, nhiệt độ lò nướng kèm chế độ quạt đối lưu (fan) và mức vạch gas (gas mark), cùng diện tích các loại khuôn
- `references/baking-scaling-caveats.md` - những gì thay đổi tuyến tính, trứng, chất tạo nở, kích thước khuôn và thời gian nướng, các lưu ý khi nấu ăn (không phải làm bánh) và quy tắc làm tròn
- `templates/scaled-recipe.md` - mẫu công thức đã quy đổi để gửi lại cho người dùng
- `examples/fudgy-brownies-8x8.csv` - công thức bánh brownie cho khuôn 8x8 (16 miếng), được sử dụng trong phần ví dụ

## Quy trình làm việc

### 1. Thu thập công thức và mục tiêu
Hỏi danh sách nguyên liệu kèm theo định lượng và đơn vị, sản lượng (yield) hoặc khuôn gốc, và mục tiêu cần đạt: số khẩu phần, hệ số nhân, hoặc một chiếc khuôn khác. Hỏi xem đây có phải là công thức làm bánh hay không, họ muốn dùng đơn vị nào (cup, gam, hay giữ nguyên như bản gốc), và công thức có nguồn gốc từ đâu nếu kích cỡ cốc (cup), thìa canh (tablespoon) hoặc trứng có thể khác biệt (Mỹ, Anh, Úc). Đưa các nguyên liệu vào tệp CSV với các cột `quantity,unit,ingredient,note`.

### 2. Chạy trình quy đổi (scaler)
```
python3 scripts/scale_recipe.py examples/fudgy-brownies-8x8.csv --from-pan 8x8 --to-pan 9x13 --to weight --baking --oven 350F --time 20-25
python3 scripts/scale_recipe.py stew.csv --servings 4 10 --to metric
python3 scripts/scale_recipe.py cake.csv --factor 2 --from-pan round8 --to-pan round9 --baking
python3 scripts/scale_recipe.py --self-test
```
Các loại khuôn: `8x8`, `9x13`, `20x30cm`, `round9`, `round23cm`, `loaf9x5`. Nếu chỉ truyền thông số khuôn, hệ số nhân sẽ là tỷ lệ diện tích giữa hai khuôn. Nếu truyền hệ số nhân hoặc khẩu phần kèm theo thông số khuôn, kịch bản sẽ kiểm tra xem độ dày của lớp bột (batter depth) thay đổi như thế nào. Mã thoát (Exit) 1 có nghĩa là có lưu ý mức HIGH (độ dày bột thay đổi hơn 1.5 lần), mã thoát 2 có nghĩa là dữ liệu đầu vào không hợp lệ.

### 3. Kiểm tra và điều chỉnh
- Đọc mọi lưu ý (caveat) và chuyển chúng thành hướng dẫn cụ thể (xem `references/baking-scaling-caveats.md`): cân phần trứng lẻ, nướng thành nhiều mẻ, đổi khuôn, hạ nhiệt độ lò, nếm thử trước khi cho toàn bộ lượng muối.
- Đối với các nguyên liệu không có dữ liệu khối lượng riêng (NO_DENSITY), hãy giữ nguyên đơn vị thể tích hoặc tra cứu trọng lượng của chúng; tuyệt đối không đoán mò đối với các nhãn hiệu muối hoặc chất tạo nở.
- Kiểm tra tính hợp lý của kết quả: khuôn có chứa vừa lượng bột không (đầy tối đa 2/3 khuôn đối với bánh bông lan/cake)? Việc làm tròn có làm lệch một nguyên liệu quan trọng quá 5 % hay không? Nếu có, hãy cung cấp định lượng bằng gam.

### 4. Bàn giao kết quả
Điền vào mẫu `templates/scaled-recipe.md`: hệ số nhân, sản lượng (yield), khuôn, nhiệt độ lò tính bằng °F và °C (có quạt đối lưu), nguyên liệu theo đơn vị của người nấu kèm đơn vị thay thế trong ngoặc vuông, các thay đổi trong cách làm, các lưu ý và cách kiểm tra độ chín thay vì một mốc thời gian cố định.

## Kết quả ví dụ
Tệp `examples/fudgy-brownies-8x8.csv` được chuyển từ khuôn 8x8 sang khuôn 9x13: hệ số nhân x1.83 (từ 64 lên 117 inch vuông), độ dày lớp bột giữ nguyên, vì vậy nướng ở nhiệt độ 350°F / 180°C (quạt đối lưu 160°C) và bắt đầu kiểm tra ở phút thứ 20. Tính theo gam: bơ 205 g, đường 365 g, bột cacao 52 g, bột mì 115 g, sô-cô-la chip 235 g, muối 2.5 g, bột nở (baking powder) 2 g, vani 7.5 g. Trứng được nhân lên thành 3.66 quả (mức MEDIUM EGG_FRACTION): sử dụng 3 quả trứng cộng với 33 g trứng đánh tan. Việc nhân đôi công thức nhưng lại nướng trong khuôn tròn 9 inch (có diện tích xấp xỉ khuôn 8x8) sẽ làm tăng gấp đôi độ dày lớp bột (mức HIGH DEPTH_CHANGE, mã thoát 1).

## Quy tắc

- Hiển thị hệ số nhân và cách bạn tính ra nó (tỷ lệ khẩu phần hoặc diện tích khuôn) trước khi liệt kê định lượng nguyên liệu.
- Tuyệt đối không nhân thời gian nướng hoặc thời gian nấu với hệ số nhân; hãy đưa ra cách kiểm tra độ chín và thời điểm bắt đầu kiểm tra sớm.
- Giữ nguyên tỷ lệ muối và chất tạo nở trong làm bánh; trong nấu ăn thông thường, chỉ thêm khoảng ba phần tư lượng gia vị mạnh đã quy đổi rồi nếm thử.
- Ưu tiên đơn vị gam khi làm bánh và nói rõ rằng khối lượng riêng chỉ là mức trung bình; hãy tin dùng số gam của tác giả công thức khi có sẵn.
- Hãy hỏi lại trước khi mặc định sử dụng cốc (cup) chuẩn Mỹ hoặc cỡ trứng chuẩn Mỹ cho các công thức đến từ những quốc gia khác.
- Nhắc đến vấn đề an toàn thực phẩm đối với các mẻ nấu lớn (làm nguội nhanh trong các khay nông) khi tăng khẩu phần các món nấu chín lên nhiều lần.
FILE:references/conversions-and-densities.md
# Bảng chuyển đổi và khối lượng riêng

## Thể tích (Hệ đo lường thông dụng của Mỹ - US customary)
| Đơn vị | ml | Tương đương |
|---|---|---|
| 1 tsp (thìa cà phê) | 4.93 | 1/3 tbsp |
| 1 tbsp (thìa canh) | 14.79 | 3 tsp |
| 1 fl oz (ounce lỏng) | 29.57 | 2 tbsp |
| 1 cup (cốc) | 236.59 | 16 tbsp, 8 fl oz |
| 1 pint | 473.18 | 2 cups |
| 1 quart | 946.35 | 4 cups |

Các loại cốc (cup) khác: cốc hệ mét (các công thức của Úc, New Zealand, Canada) = 250 ml; pint hệ Anh (UK imperial pint) = 568 ml; thìa canh của Úc = 20 ml (4 tsp). Hãy hỏi xuất xứ của công thức khi kích thước cốc hoặc thìa canh đóng vai trò quan trọng (làm bánh, muối, chất tạo nở).

## Trọng lượng
| Đơn vị | g |
|---|---|
| 1 oz | 28.35 |
| 1 lb | 453.6 (16 oz) |
| 1 thanh bơ (1 stick butter - Mỹ) | 113 (1/2 cup, 8 tbsp) |

Đơn vị "oz" trong công thức là trọng lượng trừ khi được ghi rõ là "fl oz". Đối với nước và sữa, 8 fl oz nặng khoảng 8 oz; đối với bột mì, 8 fl oz nặng khoảng 4.4 oz.

## Số gam trên mỗi cốc chuẩn Mỹ (đong bằng cách xúc thìa và gạt ngang, được sử dụng bởi kịch bản)
| Nguyên liệu | g/cup | g/tbsp | g/tsp |
|---|---|---|---|
| Bột mì đa dụng (All-purpose / plain flour) | 125 | 7.8 | 2.6 |
| Bột bánh mì (Bread flour) | 127 | 7.9 | |
| Bột làm bánh ngọt (Cake flour) | 114 | 7.1 | |
| Bột mì nguyên cám (Whole wheat flour) | 113 | 7.1 | |
| Bột hạnh nhân (Almond flour) | 96 | 6 | |
| Tinh bột ngô (Cornstarch / cornflour) | 112 | 7 | |
| Đường cát trắng hoặc đường tinh luyện mịn (Granulated / caster sugar) | 200 | 12.5 | 4.2 |
| Đường nâu, nén chặt (Brown sugar, packed) | 213 | 13.3 | |
| Đường bột (Powdered / icing sugar) | 120 | 7.5 | |
| Bơ (Butter) | 227 | 14.2 | |
| Nước (Water) | 237 | 14.8 | 4.9 |
| Sữa tươi, buttermilk, kem chua (Milk, buttermilk, sour cream) | 242 | 15.1 | |
| Kem béo (Heavy cream) | 238 | 14.9 | |
| Sữa chua (Yogurt) | 245 | 15.3 | |
| Dầu thực vật hoặc dầu hạt cải (Vegetable / canola oil) | 218 | 13.6 | |
| Dầu ô liu (Olive oil) | 216 | 13.5 | |
| Mật ong, si-rô vàng (Honey, golden syrup) | 340 | 21 | 7 |
| Si-rô cây phong (Maple syrup) | 322 | 20 | |
| Bột cacao (Cocoa powder) | 85 | 5.3 | |
| Yến mạch cán dẹt (Rolled oats) | 90 | | |
| Sô-cô-la chip (Chocolate chips) | 170 | | |
| Gạo trắng sống (Raw white rice) | 185 | | |
| Các loại hạt băm nhỏ / hạt óc chó (Chopped nuts / walnuts) | 120 | | |
| Hạt hồ đào (Pecans) | 110 | | |
| Nho khô (Raisins) | 150 | | |
| Bơ đậu phộng (Peanut butter) | 270 | 17 | |
| Muối ăn / muối hạt mịn (Table / fine salt) | 288 | 18 | 6 |
| Muối nở (Baking soda) | 230 | | 4.8 |
| Bột nở (Baking powder) | 192 | | 4 |
| Men nở lấy liền hoặc men khô kích hoạt (Instant / active dry yeast) | 149 | | 3.1 |
| Tinh chất vani (Vanilla extract) | 202 | | 4.2 |
| Bột quế (Ground cinnamon) | 125 | | 2.6 |

Lưu ý:
- Bột mì múc trực tiếp từ túi bằng cốc đong có thể nặng từ 140 đến 150 g mỗi cốc. Nếu tác giả công thức cung cấp số gam, hãy tin dùng số gam đó.
- Muối Kosher phụ thuộc vào thương hiệu: Diamond Crystal nặng khoảng 2.8 g/tsp, Morton khoảng 5 g/tsp, muối ăn thông thường khoảng 6 g/tsp. Việc đổi thương hiệu muối nhưng đong theo thể tích có thể làm tăng gấp đôi lượng muối. Kịch bản sẽ giữ nguyên "kosher salt" ở đơn vị thể tích và đưa ra thông báo rõ ràng.
- Bảng trên là mức trung bình thực tế; các bảng công bố khác nhau có thể chênh lệch khoảng 5 %. Mức này hoàn toàn ổn đối với việc nấu ăn và hầu hết các món bánh; riêng đối với bánh macaron, bánh mì và kẹo, hãy dùng cân.

## Trứng
| Kích cỡ (Mỹ) | Trọng lượng bỏ vỏ |
|---|---|
| Cỡ lớn (Large) | 50 g (lòng đỏ 18 g, lòng trắng 32 g), khoảng 3 tbsp sau khi đánh tan |
| Cỡ vừa (Medium) | 44 g |
| Cỡ rất lớn (Extra large) | 56 g |
| Cỡ đại (Jumbo) | 63 g |
Trứng cỡ "large" của Anh/Châu Âu (63 đến 73 g tính cả vỏ) nặng khoảng 58 g khi bỏ vỏ: một quả trứng cỡ large của Anh gần với cỡ extra large của Mỹ hơn.

## Nhiệt độ lò nướng
| °F | °C | °C có quạt (Fan) | Mức Gas (Gas mark) |
|---|---|---|---|
| 300 | 150 | 130 | 2 |
| 325 | 160 | 140 | 3 |
| 350 | 180 | 160 | 4 |
| 375 | 190 | 170 | 5 |
| 400 | 200 | 180 | 6 |
| 425 | 220 | 200 | 7 |
| 450 | 230 | 210 | 8 |
Lò nướng có quạt (đối lưu): hạ thấp khoảng 20 °C / 25 °F, hoặc giữ nguyên nhiệt độ và kiểm tra bánh sớm hơn.

## Diện tích khuôn
| Khuôn | Diện tích (inch vuông - sq in) | Diện tích (cm²) |
|---|---|---|
| Vuông 8x8 | 64 | 413 |
| Vuông 9x9 | 81 | 523 |
| Chữ nhật 9x13 | 117 | 755 |
| Khay bánh cuộn (jelly roll) 10x15 | 150 | 968 |
| Tròn 8 in | 50 | 324 |
| Tròn 9 in | 64 | 410 |
| Tròn 10 in | 79 | 507 |
| Khuôn bánh mì gối (loaf) 9x5 | 45 | 290 |
| Tròn 20 cm | 49 | 314 |
| Tròn 23 cm | 64 | 415 |
| Vuông 20x20 cm | 62 | 400 |
Diện tích khuôn tròn = 3.14 x bán kính². Một chiếc khuôn vuông 8x8 và một chiếc khuôn tròn 9 in chứa lượng bột gần như tương đương nhau.
FILE:references/baking-scaling-caveats.md
# Các lưu ý khi quy đổi công thức

## Những gì thay đổi theo tỷ lệ tuyến tính
Bột mì, đường, chất béo, chất lỏng, sô-cô-la, các loại hạt, trái cây và trứng (tính theo trọng lượng) thay đổi tuyến tính theo hệ số nhân. Trong làm bánh, muối và chất tạo nở cũng bắt đầu ở mức định lượng tuyến tính: phản ứng hóa học phụ thuộc vào tỷ lệ so với bột mì, vì vậy hãy giữ nguyên tỷ lệ đó.

## Trứng
- Phần lẻ của trứng: đánh tan trứng, đem cân và lấy đúng số gam cần thiết (trứng cỡ lớn = 50 g khi bỏ vỏ). 3.66 quả trứng = 3 quả trứng + 33 g trứng đánh tan (khoảng 2 tbsp).
- Nếu bạn chọn cách làm tròn: nhiều trứng hơn sẽ làm bánh bông lan (cake) và bánh brownie cứng cáp hơn, xốp giống bánh bông lan hơn hoặc béo ngậy hơn; ít trứng hơn sẽ làm bánh đặc hơn và dễ vỡ hơn. Khi phân vân, hãy làm tròn lên đối với bánh bông lan, và làm tròn xuống đối với bánh brownie ẩm đặc (fudgy brownies) và bánh quy.
- Các công thức được viết ở quốc gia khác có thể sử dụng kích cỡ trứng khác (xem bảng chuyển đổi).

## Chất tạo nở (bột nở, muối nở, men nở)
- Bắt đầu theo tỷ lệ tuyến tính và đong đếm thật chính xác; ở các hệ số nhân nhỏ, sai số 1/8 tsp là rất lớn, vì vậy hãy cân trên cân tiểu ly có độ chia 0.1 g.
- Đối với các hệ số nhân lớn hơn 2, quá trình trộn bột và nhiệt lượng lò nướng không tăng theo tỷ lệ tuyến tính: khối bột lớn khó trộn đều hơn và phần tâm bánh nóng lên chậm hơn. Hãy chia thành các mẻ riêng biệt theo kích thước gốc bất cứ khi nào có thể.
- Nếu lớp bột cuối cùng dày hơn so với bản gốc (cùng một khuôn nhưng nhiều bột hơn), phần tâm bánh sẽ nở chậm hơn. Đừng "chữa cháy" việc này bằng cách cho thêm chất tạo nở; hãy dùng khuôn rộng hơn hoặc hạ nhiệt độ lò và nướng lâu hơn.
- Bánh mì: men nở thay đổi tuyến tính theo lượng bột mì; thời gian ủ nở phụ thuộc vào nhiệt độ khối bột chứ không phụ thuộc vào khối lượng bột.

## Kích thước khuôn và thời gian nướng
- Quy đổi theo diện tích khuôn giúp giữ nguyên độ dày của lớp bột, do đó thời gian nướng gần như không đổi. Hãy bắt đầu kiểm tra sớm hơn 5 phút.
- Cùng một lượng bột công thức nhưng cho vào khuôn khác: tỷ lệ độ dày = diện tích khuôn cũ / diện tích khuôn mới. Lớp bột dày hơn cần thời gian nướng lâu hơn ở nhiệt độ thấp hơn (thấp hơn khoảng 25 °F / 15 °C); lớp bột mỏng hơn sẽ chín nhanh hơn.
- Chỉ đổ bột vào khuôn bánh bông lan tối đa 2/3 khuôn, và khoảng một nửa khuôn đối với bánh brownie.
- Khuôn thủy tinh và khuôn kim loại tối màu làm chín phần rìa bánh nhanh hơn: hãy hạ nhiệt độ lò xuống 25 °F / 15 °C.
- Làm bánh cupcake từ công thức bánh bông lan: nướng từ 18 đến 22 phút ở cùng mức nhiệt độ; một công thức bánh khuôn 9x13 làm được khoảng 24 chiếc bánh cupcake.
- Tuyệt đối không nhân thời gian nướng với hệ số quy đổi. Hãy sử dụng phương pháp kiểm tra độ chín từ công thức gốc (cắm tăm rút ra còn dính vụn ẩm đối với bánh brownie, rút tăm sạch khô đối với bánh bông lan, nhiệt độ bên trong đạt 93 đến 99 °C / 200 đến 210 °F đối với bánh mì).

## Nấu ăn thông thường (không phải làm bánh)
- Gia vị: chỉ cho khoảng ba phần tư lượng muối, ớt và các loại gia vị mạnh đã nhân theo hệ số, sau đó nếm thử. Một chiếc nồi lớn hơn sẽ có tốc độ bay hơi khác đi.
- Chất lỏng trong các món hầm và súp: sự bay hơi phụ thuộc vào diện tích bề mặt của nồi chứ không phải thể tích, vì vậy một món hầm được nhân đôi nấu trong nồi rộng hơn có thể cần lượng chất lỏng bổ sung ít hơn mức gấp đôi (2x).
- Áp chảo và chiên rán: hãy chia thành từng mẻ; chảo quá chật sẽ làm thức ăn bị hấp chín bằng hơi nước thay vì vàng xém.
- Thời gian: một nồi lớn gấp đôi sẽ mất nhiều thời gian hơn để đun sôi và làm nguội, nhưng thời gian ninh nhỏ lửa (simmering) khi đã sôi thì gần như tương đương. Các món thịt quay/nướng tảng phụ thuộc vào độ dày của miếng thịt chứ không phải tổng trọng lượng: hãy dùng nhiệt kế đo thịt.
- An toàn thực phẩm: làm nguội nhanh các mẻ thức ăn lớn (chia nhỏ ra các khay nông) và hâm nóng lại ở nhiệt độ tối thiểu 74 °C / 165 °F.

## Quy tắc làm tròn cho căn bếp thực tế
- Đơn vị đo lường Mỹ (US measures): cốc (cup) làm tròn theo nấc 1/4 và 1/3, phần dư chuyển sang thìa canh (tbsp) làm tròn theo nấc một nửa (1/2), và thìa cà phê (tsp) làm tròn xuống tối thiểu 1/8. Nhỏ hơn 1/8 tsp = một nhúm (a pinch).
- Hệ mét: làm tròn đến 0.5 g đối với lượng dưới 10 g, 1 g đối với lượng dưới 100 g, và 5 g đối với lượng dưới 1 kg.
- Giữ nguyên hệ thống đơn vị gốc trừ khi người nấu yêu cầu đổi; luôn đề xuất đơn vị gam cho các món bánh.
- Kiểm tra lại kết quả sau khi làm tròn so với tỷ lệ gốc (ví dụ tỷ lệ giữa bột mì và bơ); nếu việc làm tròn làm dịch chuyển một nguyên liệu quan trọng quá 5 %, hãy cung cấp số gam chính xác.
FILE:templates/scaled-recipe.md
# <Tên công thức>, đã quy đổi <từ khuôn 8x8 sang khuôn 9x13 / từ 4 lên 10 khẩu phần>

**Hệ số nhân:** x<1.83>   **Sản lượng:** <24 miếng brownie / 10 khẩu phần>   **Đơn vị:** <gam kèm đơn vị đo lường Mỹ trong ngoặc>
**Khuôn:** <9x13 in (23x33 cm), có lót giấy nến>   **Lò nướng:** <350°F / 180°C (quạt đối lưu 160°C)>   **Thời gian nướng:** <bắt đầu kiểm tra ở phút 20; thường từ 20-25 phút>

## Nguyên liệu
| Nguyên liệu | Định lượng | Đơn vị đo lường Mỹ |
|---|---|---|
| <bơ lạt, đun chảy> | <205 g> | <3/4 cup + 2 1/2 tbsp> |
| <trứng gà cỡ lớn (large)> | <3 quả + 33 g đánh tan (khoảng 2 tbsp)> | |

## Thay đổi trong cách làm so với bản gốc
- <Đánh tan 4 quả trứng, cân lấy 183 g, giữ lại phần thừa để phết mặt bánh (egg wash)>
- <Trộn trong âu lớn hơn; chia bột mì thành hai lần để trộn (fold) vào hỗn hợp>
- <Giữ nguyên thời gian nướng vì độ dày lớp bột không đổi; kiểm tra ở phút thứ 20>

## Các lưu ý (Caveats)
- <EGG_FRACTION: ...>
- <Thương hiệu muối Kosher: ...>

## Kiểm tra độ chín
<Cắm tăm cách tâm bánh 2 cm, khi rút ra thấy có vụn bánh ẩm bám vào chứ không phải bột ướt.>
FILE:examples/fudgy-brownies-8x8.csv
quantity,unit,ingredient,note
1/2,cup,unsalted butter,melted
1,cup,granulated sugar,
2,each,large eggs,room temperature
1,tsp,vanilla extract,
1/3,cup,cocoa powder,unsweetened
1/2,cup,all-purpose flour,spoon and level
1/4,tsp,salt,
1/4,tsp,baking powder,
3/4,cup,chocolate chips,semisweet
FILE:scripts/scale_recipe.py
#!/usr/bin/env python3
"""Recipe scaling and unit converter (Python 3 standard library only).

Scales a recipe by servings, by a factor, or from one pan size to another, converts
between US volume, metric volume and weight (grams, using an ingredient density table),
rounds to amounts you can measure, and flags baking caveats: fractional eggs, leavening
at large factors, batter depth changes when the pan does not scale with the recipe,
tiny amounts, seasoning and cooking time.

Input CSV columns: quantity,unit,ingredient,note
  quantity: 2 | 1.5 | 3/4 | 1 1/2 | ½   unit: tsp tbsp cup fl oz pint quart ml l g kg oz lb stick
  each (or empty) for counted items such as eggs.
Usage:
  python3 scale_recipe.py recipe.csv --servings 4 10 [--to us|metric|weight|keep]
  python3 scale_recipe.py recipe.csv --from-pan 8x8 --to-pan 9x13 --baking --oven 350F --time 20-25
  python3 scale_recipe.py recipe.csv --factor 0.5 --to weight --json
  python3 scale_recipe.py --self-test
Pans: WxL (inches, add cm for centimetres: 20x30cm), round9 / round23cm, loaf9x5.
Exit codes: 0 = no HIGH findings, 1 = HIGH findings, 2 = bad input.
"""
import argparse, csv, io, json, math, re, sys

ML = {"tsp": 4.92892, "tbsp": 14.7868, "cup": 236.588, "fl oz": 29.5735, "pint": 473.176,
      "quart": 946.353, "ml": 1.0, "l": 1000.0}
G = {"g": 1.0, "kg": 1000.0, "oz": 28.3495, "lb": 453.592, "stick": 113.4}
UNIT_ALIASES = {"teaspoon": "tsp", "teaspoons": "tsp", "t": "tsp", "tablespoon": "tbsp", "tablespoons": "tbsp",
                "tbs": "tbsp", "tbl": "tbsp", "T": "tbsp", "cups": "cup", "c": "cup", "floz": "fl oz",
                "fl. oz": "fl oz", "fluid ounce": "fl oz", "fluid ounces": "fl oz", "pints": "pint", "pt": "pint",
                "quarts": "quart", "qt": "quart", "milliliter": "ml", "milliliters": "ml", "mL": "ml",
                "liter": "l", "liters": "l", "litre": "l", "litres": "l", "L": "l", "gram": "g", "grams": "g",
                "kilogram": "kg", "kilograms": "kg", "ounce": "oz", "ounces": "oz", "pound": "lb", "pounds": "lb",
                "lbs": "lb", "sticks": "stick", "": "each", "x": "each", "whole": "each", "pc": "each",
                "pcs": "each", "piece": "each", "pieces": "each", "clove": "each", "cloves": "each",
                "large": "each", "medium": "each", "small": "each", "pinch": "pinch", "pinches": "pinch",
                "dash": "pinch"}
# grams per US cup (spoon-and-level). Longest matching name wins.
DENSITY = {
    "all-purpose flour": 125, "plain flour": 125, "flour": 125, "bread flour": 127, "cake flour": 114,
    "whole wheat flour": 113, "almond flour": 96, "cornstarch": 112, "cornflour": 112,
    "granulated sugar": 200, "caster sugar": 200, "sugar": 200, "brown sugar": 213,
    "powdered sugar": 120, "icing sugar": 120, "confectioners sugar": 120,
    "butter": 227, "water": 237, "milk": 242, "buttermilk": 242, "heavy cream": 238, "cream": 238,
    "sour cream": 242, "yogurt": 245, "vegetable oil": 218, "canola oil": 218, "olive oil": 216, "oil": 218,
    "honey": 340, "maple syrup": 322, "golden syrup": 340, "cocoa powder": 85, "cocoa": 85,
    "rolled oats": 90, "oats": 90, "chocolate chips": 170, "rice": 185, "chopped nuts": 120,
    "walnuts": 120, "pecans": 110, "raisins": 150, "peanut butter": 270,
    "table salt": 288, "fine salt": 288, "salt": 288, "kosher salt": None,
    "baking soda": 230, "bicarbonate of soda": 230, "baking powder": 192, "instant yeast": 149,
    "active dry yeast": 149, "yeast": 149, "vanilla extract": 202, "vanilla": 202,
    "ground cinnamon": 125, "cinnamon": 125,
}
LEAVENERS = ("baking soda", "bicarbonate", "baking powder", "yeast", "cream of tartar")
SEASONINGS = ("salt", "pepper", "chili", "chilli", "cayenne", "pepper flakes", "garlic powder", "curry", "cumin", "paprika")
EGG_G = {"egg": 50.0, "yolk": 18.0, "white": 32.0}  # US large egg out of shell
UNICODE_FRAC = {"½": .5, "¼": .25, "¾": .75, "⅓": 1 / 3, "⅔": 2 / 3, "⅛": .125, "⅜": .375, "⅝": .625, "⅞": .875}
SEV_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}


def parse_qty(s):
    s = s.strip()
    for ch, v in UNICODE_FRAC.items():
        if ch in s:
            rest = s.replace(ch, "").strip()
            return (float(rest) if rest else 0.0) + v
    m = re.fullmatch(r"(\d+)\s+(\d+)/(\d+)", s)
    if m:
        return int(m[1]) + int(m[2]) / int(m[3])
    m = re.fullmatch(r"(\d+)/(\d+)", s)
    if m:
        return int(m[1]) / int(m[2])
    m = re.fullmatch(r"\d+(?:\.\d+)?|\.\d+", s)
    if m:
        return float(s)
    raise ValueError(f"cannot read quantity {s!r}")


def norm_unit(u):
    u = u.strip()
    if u in UNIT_ALIASES:
        return UNIT_ALIASES[u]
    low = u.lower().rstrip(".")
    if low in ML or low in G or low in ("each", "pinch"):
        return low
    if low in UNIT_ALIASES:
        return UNIT_ALIASES[low]
    raise ValueError(f"unknown unit {u!r}")


def density_for(name):
    low = name.lower()
    best = None
    for key in DENSITY:
        if re.search(r"\b" + re.escape(key) + r"\b", low) and (best is None or len(key) > len(best)):
            best = key
    return (best, DENSITY[best]) if best else (None, None)


def egg_kind(name):
    low = name.lower()
    if "yolk" in low:
        return "yolk"
    if "white" in low and "egg" in low:
        return "white"
    if re.search(r"\beggs?\b", low):
        return "egg"
    return None


def parse_pan(spec):
    s = spec.strip().lower().replace(" ", "").replace("inch", "").replace("in", "").replace('"', "")
    cm = s.endswith("cm")
    if cm:
        s = s[:-2]
    k = 1 / 2.54 if cm else 1.0
    m = re.fullmatch(r"(?:round)?(\d+(?:\.\d+)?)(?:round)?", s)
    if m and "round" in s:
        d = float(m[1]) * k
        return math.pi * (d / 2) ** 2, f"{spec} round ({d:.1f} in)"
    m = re.fullmatch(r"(?:loaf|square|rect)?(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)", s)
    if m:
        a, b = float(m[1]) * k, float(m[2]) * k
        return a * b, f"{spec} ({a:.1f} x {b:.1f} in)"
    raise ValueError(f"cannot read pan size {spec!r} (use 9x13, 20x30cm, round9, round23cm, loaf9x5)")


def frac_str(x, denoms=(2, 3, 4, 8)):
    whole = int(x)
    rest = x - whole
    best = (abs(rest), 0, 1)
    for d in denoms:
        n = round(rest * d)
        if 0 < n < d and abs(rest - n / d) < best[0] - 1e-9:
            best = (abs(rest - n / d), n, d)
    if abs(rest - 1) < best[0]:
        return str(whole + 1)
    _, n, d = best
    if n == 0:
        return str(whole)
    g = math.gcd(n, d)
    return (f"{whole} " if whole else "") + f"{n // g}/{d // g}"


def frac_val(s):
    return parse_qty(s)


def cup_word(x):
    return "cups" if x > 1 + 1e-9 else "cup"


def fmt_us_volume(ml):
    cups = ml / ML["cup"]
    if cups >= 0.25 - 1e-9:
        s = frac_str(cups, (2, 3, 4))
        err = abs(frac_val(s) - cups) * ML["cup"]
        if err >= ML["tbsp"] * 0.75:
            base = math.floor(cups * 4) / 4
            tb = (cups - base) * ML["cup"] / ML["tbsp"]
            bs = frac_str(base, (4,))
            return (f"{bs} {cup_word(base)} + " if base else "") + f"{frac_str(tb, (2,))} tbsp"
        return f"{s} {cup_word(frac_val(s))}"
    tbsp = ml / ML["tbsp"]
    if tbsp >= 1 - 1e-9:
        return f"{frac_str(tbsp, (2,))} tbsp"
    tsp = ml / ML["tsp"]
    if tsp < 1 / 16:
        return "pinch"
    return f"{frac_str(tsp, (2, 4, 8))} tsp"


def round_metric(x):
    if x < 10:
        return round(x * 2) / 2
    if x < 100:
        return round(x)
    if x < 1000:
        return round(x / 5) * 5
    return round(x / 10) * 10


def fmt_num(x):
    return f"{x:g}"


def fmt_metric(amount, unit):
    v = round_metric(amount)
    if v >= 2000:
        return f"{fmt_num(v / 1000)} {'kg' if unit == 'g' else 'l'}"
    return f"{fmt_num(v)} {unit}"


def fmt_us_weight(g):
    oz = g / G["oz"]
    if oz >= 16:
        lb = oz / 16
        return f"{frac_str(lb, (4,))} lb"
    return f"{frac_str(oz, (2, 4))} oz" if oz >= 1 else f"{fmt_num(round(oz, 2))} oz"


def convert(row, factor, target):
    """Return dict with scaled display and notes for one ingredient row."""
    qty, unit, name = row["qty"] * factor, row["unit"], row["ingredient"]
    key, dens = density_for(name)
    egg = egg_kind(name)
    out = {"ingredient": name, "original": row["original"], "scaled_qty": qty, "unit": unit, "notes": []}
    if unit == "each":
        if egg:
            g = qty * EGG_G[egg]
            out["display"] = f"{fmt_num(round(qty, 2))} ({fmt_metric(g, 'g')} beaten)"
        else:
            out["display"] = fmt_num(round(qty, 2))
        return out
    if unit == "pinch":
        out["display"] = f"{fmt_num(round(qty, 2))} pinch"
        return out
    if unit in ML:
        ml = qty * ML[unit]
        out["ml"] = ml
        if target == "weight":
            if dens:
                out["display"] = fmt_metric(ml / ML["cup"] * dens, "g")
                out["also"] = fmt_us_volume(ml)
            else:
                out["display"] = fmt_metric(ml, "ml")
                out["also"] = fmt_us_volume(ml)
                out["notes"].append("NO_DENSITY")
        elif target == "metric" or (target == "keep" and unit in ("ml", "l")):
            out["display"] = fmt_metric(ml, "ml")
            out["also"] = fmt_us_volume(ml)
        else:
            out["display"] = fmt_us_volume(ml)
            out["also"] = fmt_metric(ml, "ml") if not dens else fmt_metric(ml / ML["cup"] * dens, "g")
        return out
    g = qty * G[unit]
    out["g"] = g
    if target == "us" or (target == "keep" and unit in ("oz", "lb", "stick")):
        if unit == "stick" and target == "keep":
            out["display"] = f"{frac_str(qty, (2, 4))} stick ({fmt_metric(g, 'g')})"
        else:
            out["display"] = fmt_us_weight(g)
        out["also"] = fmt_metric(g, "g")
    else:
        out["display"] = fmt_metric(g, "g")
        if dens:
            out["also"] = fmt_us_volume(g / dens * ML["cup"])
    return out


def read_recipe(text):
    rows = []
    reader = csv.DictReader(io.StringIO(text.lstrip("\ufeff")))
    need = {"quantity", "unit", "ingredient"}
    if not reader.fieldnames or not need <= {f.strip().lower() for f in reader.fieldnames}:
        raise ValueError("CSV header must include quantity,unit,ingredient (note optional)")
    for i, r in enumerate(reader, 2):
        r = {k.strip().lower(): (v or "").strip() for k, v in r.items() if k}
        if not r.get("ingredient"):
            continue
        try:
            qty = parse_qty(r["quantity"])
            unit = norm_unit(r.get("unit", ""))
        except ValueError as e:
            raise ValueError(f"line {i}: {e}")
        orig = f"{r['quantity']} {r.get('unit', '')}".strip()
        rows.append({"qty": qty, "unit": unit, "ingredient": r["ingredient"], "note": r.get("note", ""), "original": orig})
    if not rows:
        raise ValueError("no ingredient rows")
    return rows


def oven(temp):
    m = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*°?\s*([CcFf])\s*", temp)
    if not m:
        raise ValueError(f"cannot read oven temperature {temp!r} (use 350F or 180C)")
    v, u = float(m[1]), m[2].upper()
    if u == "F":
        c = (v - 32) * 5 / 9
        return f"{v:g}°F = {round(c / 10) * 10:g}°C (fan oven {round(c / 10) * 10 - 20:g}°C)"
    f = v * 9 / 5 + 32
    return f"{v:g}°C = {round(f / 25) * 25:g}°F"


def scale(rows, factor, target="keep", baking=False, depth_ratio=None, pan_change=None, bake_time=None):
    items = [convert(r, factor, target) for r in rows]
    findings = []
    for it, r in zip(items, rows):
        name = r["ingredient"].lower()
        egg = egg_kind(name)
        if egg and r["unit"] == "each":
            q = it["scaled_qty"]
            whole = math.floor(q + 1e-9)
            if abs(q - round(q)) > 0.15:
                extra = (q - whole) * EGG_G[egg]
                findings.append(("MEDIUM", "EGG_FRACTION", r["ingredient"],
                                 f"scales to {q:.2f} {egg}s",
                                 f"Use {whole} whole {egg}{'s' if whole != 1 else ''} plus {round(extra):g} g beaten {egg} (a large {egg} is about {EGG_G[egg]:g} g out of the shell), or round to {round(q)} and expect a {'richer' if round(q) > q else 'drier'} result."))
        if "NO_DENSITY" in it["notes"]:
            findings.append(("LOW", "NO_DENSITY", r["ingredient"], "no density in the table, so it stays in volume",
                             "Weigh it once, or look up grams per cup; for kosher salt the brand matters (Diamond Crystal about 136 g/cup, Morton about 240 g/cup)."))
        ml = it.get("ml")
        if ml is not None and ml / ML["tsp"] < 1 / 8 and r["unit"] in ML:
            findings.append(("LOW", "TINY_AMOUNT", r["ingredient"], f"scales to {ml / ML['tsp']:.2f} tsp",
                             "Use a pinch or a 1/8 tsp measure; for leavening weigh on a 0.1 g scale."))
        if baking and any(w in name for w in LEAVENERS) and (factor > 2 or factor < 0.5):
            findings.append(("LOW", "LEAVENING", r["ingredient"], f"leavening scaled x{factor:.2f}",
                             "Linear scaling is the starting point; measure exactly (weigh), and for factors above 2 consider separate batches because mixing and oven heat do not scale."))
        if not baking and factor > 2 and any(w in name for w in SEASONINGS):
            findings.append(("INFO", "SEASONING", r["ingredient"], f"seasoning scaled x{factor:.2f}",
                             "Add about three quarters, then taste and adjust; evaporation and pot size change how salty or hot it ends up."))
    if baking and (factor > 3 or factor < 1 / 3):
        findings.append(("MEDIUM", "BIG_FACTOR", "-", f"baking recipe scaled x{factor:.2f}",
                         "Bake in several batches of the original size, or check mixer bowl capacity; never multiply the bake time."))
    if depth_ratio is not None:
        sev = "HIGH" if (depth_ratio > 1.5 or depth_ratio < 0.67) else ("MEDIUM" if (depth_ratio > 1.25 or depth_ratio < 0.8) else None)
        if sev and baking:
            if depth_ratio > 1:
                fix = "Batter will be deeper: lower the oven by 25°F/15°C, bake longer and test the centre, keep the pan at most 2/3 full, or use a bigger pan."
            else:
                fix = "Batter will be thinner: start checking 25 to 40 % earlier, or use a smaller pan."
            findings.append((sev, "DEPTH_CHANGE", "-", f"batter depth changes x{depth_ratio:.2f} versus the original pan", fix))
    if baking and pan_change:
        if depth_ratio is None or 0.9 <= depth_ratio <= 1.1:
            tip = "Batter depth stays about the same, so the bake time stays about the same; start checking 5 minutes early. Glass or dark pans bake faster: lower 25°F/15°C."
        elif 0.8 <= depth_ratio <= 1.25:
            tip = f"Batter depth changes slightly (x{depth_ratio:.2f}); {'bake a few minutes longer' if depth_ratio > 1 else 'start checking a few minutes early'} and test the centre."
        else:
            tip = "See DEPTH_CHANGE for time and temperature."
        if bake_time:
            tip = f"Original {bake_time} min. " + tip
        findings.append(("INFO", "PAN_TIME", "-", pan_change, tip))
    if not baking and factor > 1.5:
        findings.append(("INFO", "COOK_TIME", "-", f"scaled x{factor:.2f}",
                         "Cooking time does not scale with quantity: brown meat in batches, allow longer to come to a boil, and use a pot that keeps the depth similar."))
    findings.sort(key=lambda f: SEV_ORDER[f[0]])
    return items, [dict(zip(("severity", "code", "ingredient", "problem", "fix"), f)) for f in findings]


def render(path, factor, how, target, items, findings, oven_line=None):
    out = [f"# Scaled recipe: {path}", "", f"Scale: {how} -> factor x{factor:.3f}   Units: {target}", ""]
    out += ["| Ingredient | Original | Scaled | Also |", "|---|---|---|---|"]
    for it in items:
        out.append(f"| {it['ingredient']} | {it['original']} | {it['display']} | {it.get('also', '')} |")
    if oven_line:
        out += ["", f"Oven: {oven_line}"]
    out += ["", "## Notes", ""]
    if findings:
        out += ["| Severity | Code | Ingredient | Problem | Advice |", "|---|---|---|---|---|"]
        for f in findings:
            out.append(f"| {f['severity']} | {f['code']} | {f['ingredient']} | {f['problem']} | {f['fix']} |")
    else:
        out.append("No caveats.")
    out += ["", "Weights for volume ingredients use spoon-and-level densities; weigh flour if you can."]
    return "\n".join(out)


def self_test():
    cases = []
    def t(name, cond):
        cases.append((name, bool(cond)))
    close = lambda a, b, tol=1e-6: abs(a - b) <= tol
    t("parse 1 1/2", close(parse_qty("1 1/2"), 1.5))
    t("parse 3/4 and .5 and ½", close(parse_qty("3/4"), .75) and close(parse_qty(".5"), .5) and close(parse_qty("1½"), 1.5))
    t("bad quantity rejected", raises(lambda: parse_qty("some")))
    t("unit aliases", norm_unit("Tablespoons") == "tbsp" and norm_unit("T") == "tbsp" and norm_unit("t") == "tsp" and norm_unit("") == "each")
    t("unknown unit rejected", raises(lambda: norm_unit("handful")))
    t("longest density match", density_for("light brown sugar")[0] == "brown sugar" and density_for("all-purpose flour")[1] == 125)
    t("salt vs kosher salt", density_for("salt")[1] == 288 and density_for("kosher salt")[1] is None)
    t("eggs detected", egg_kind("large eggs") == "egg" and egg_kind("egg yolks") == "yolk" and egg_kind("eggplant") is None)
    a8 = parse_pan("8x8")[0]; a913 = parse_pan("9x13")[0]
    t("rect pan area", close(a8, 64) and close(a913, 117))
    t("round pan area", close(parse_pan("round9")[0], math.pi * 20.25))
    t("cm pan", close(parse_pan("20x20cm")[0], (20 / 2.54) ** 2))
    t("bad pan rejected", raises(lambda: parse_pan("big")))
    t("us volume 1 cup", fmt_us_volume(236.588) == "1 cup")
    t("us volume 3/4 cup", fmt_us_volume(ML["cup"] * .75) == "3/4 cup")
    t("us volume 2/3 cup", fmt_us_volume(ML["cup"] * 2 / 3) == "2/3 cup")
    t("us volume cup + tbsp", fmt_us_volume(ML["cup"] * 1.125) == "1 cup + 2 tbsp")
    t("fractions reduced, cups plural", fmt_us_volume(ML["cup"] * 0.61) == "1/2 cup + 2 tbsp" and fmt_us_volume(ML["cup"] * 2) == "2 cups")
    t("us volume tbsp", fmt_us_volume(ML["tbsp"] * 1.5) == "1 1/2 tbsp")
    t("us volume tsp", fmt_us_volume(ML["tsp"] * .5) == "1/2 tsp")
    t("us volume pinch", fmt_us_volume(ML["tsp"] * .05) == "pinch")
    t("metric rounding", round_metric(7.3) == 7.5 and round_metric(57.4) == 57 and round_metric(228) == 230 and round_metric(1234) == 1230)
    t("1 cup flour = 125 g", convert({"qty": 1, "unit": "cup", "ingredient": "all-purpose flour", "original": ""}, 1, "weight")["display"] == "125 g")
    t("1 stick butter in us/keep", "1 stick" in convert({"qty": 1, "unit": "stick", "ingredient": "butter", "original": ""}, 1, "keep")["display"])
    t("8 oz to grams", convert({"qty": 8, "unit": "oz", "ingredient": "cheese", "original": ""}, 1, "metric")["display"] == "225 g")
    t("500 g to us lb", convert({"qty": 500, "unit": "g", "ingredient": "pasta", "original": ""}, 1, "us")["display"] == "1 lb")
    t("metric volume", convert({"qty": 1, "unit": "cup", "ingredient": "milk", "original": ""}, 2, "metric")["display"] == "475 ml")
    t("no density keeps ml", "NO_DENSITY" in convert({"qty": 1, "unit": "tbsp", "ingredient": "fish sauce", "original": ""}, 1, "weight")["notes"])
    rows = read_recipe("quantity,unit,ingredient,note\n2,each,large eggs,\n1/4,tsp,baking soda,\n1,cup,sugar,\n")
    t("csv read", len(rows) == 3 and rows[0]["unit"] == "each")
    t("csv bad header rejected", raises(lambda: read_recipe("a,b\n1,2\n")))
    t("csv bad unit names line", "line 2" in err_of(lambda: read_recipe("quantity,unit,ingredient\n1,handful,x\n")))
    _, f = scale(rows, 1.828, baking=True)
    t("EGG_FRACTION at x1.83", any(x["code"] == "EGG_FRACTION" and "3 whole eggs plus 33 g" in x["fix"] for x in f))
    _, f = scale(rows, 2.0, baking=True)
    t("no EGG_FRACTION when whole", not any(x["code"] == "EGG_FRACTION" for x in f))
    _, f = scale(rows, 0.1, baking=True)
    t("TINY_AMOUNT and BIG_FACTOR", {"TINY_AMOUNT", "BIG_FACTOR", "LEAVENING"} <= {x["code"] for x in f})
    _, f = scale(rows, 1.0, baking=True, depth_ratio=1.83)
    t("DEPTH_CHANGE HIGH", any(x["code"] == "DEPTH_CHANGE" and x["severity"] == "HIGH" for x in f))
    _, f = scale(rows, 1.0, baking=True, depth_ratio=1.3)
    t("DEPTH_CHANGE MEDIUM", any(x["code"] == "DEPTH_CHANGE" and x["severity"] == "MEDIUM" for x in f))
    _, f = scale(read_recipe("quantity,unit,ingredient\n1,tsp,salt\n"), 3, baking=False)
    t("SEASONING and COOK_TIME for cooking", {"SEASONING", "COOK_TIME"} <= {x["code"] for x in f})
    t("oven F to C", oven("350F") == "350°F = 180°C (fan oven 160°C)" and oven("200C") == "200°C = 400°F")
    t("findings sorted HIGH first", scale(rows, 1.83, baking=True, depth_ratio=2)[1][0]["severity"] == "HIGH")
    passed = sum(ok for _, ok in cases)
    for name, ok in cases:
        print(("PASS " if ok else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def raises(fn):
    try:
        fn()
    except ValueError:
        return True
    return False


def err_of(fn):
    try:
        fn()
    except ValueError as e:
        return str(e)
    return ""


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("recipe", nargs="?")
    g = ap.add_mutually_exclusive_group()
    g.add_argument("--servings", nargs=2, type=float, metavar=("FROM", "TO"))
    g.add_argument("--factor", type=float)
    ap.add_argument("--from-pan")
    ap.add_argument("--to-pan")
    ap.add_argument("--to", default="keep", choices=["keep", "us", "metric", "weight"])
    ap.add_argument("--baking", action="store_true", help="apply baking caveats (eggs, leavening, pan depth)")
    ap.add_argument("--oven", help="original oven temperature, e.g. 350F or 180C")
    ap.add_argument("--time", help="original bake time in minutes, e.g. 20-25")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    if not a.recipe:
        ap.print_usage(sys.stderr); return 2
    try:
        rows = read_recipe(open(a.recipe, encoding="utf-8").read())
        depth_ratio = pan_change = None
        if bool(a.from_pan) != bool(a.to_pan):
            raise ValueError("give both --from-pan and --to-pan")
        if a.from_pan:
            fa, fd = parse_pan(a.from_pan)
            ta, td = parse_pan(a.to_pan)
            pan_change = f"{fd} -> {td}, area x{ta / fa:.2f}"
        if a.servings:
            if a.servings[0] <= 0 or a.servings[1] <= 0:
                raise ValueError("servings must be positive")
            factor, how = a.servings[1] / a.servings[0], f"{a.servings[0]:g} -> {a.servings[1]:g} servings"
        elif a.factor is not None:
            if a.factor <= 0:
                raise ValueError("factor must be positive")
            factor, how = a.factor, f"factor {a.factor:g}"
        elif a.from_pan:
            factor, how = ta / fa, f"pan {a.from_pan} -> {a.to_pan}"
        else:
            raise ValueError("give --servings FROM TO, --factor F or --from-pan/--to-pan")
        if a.from_pan:
            depth_ratio = factor * fa / ta
            if abs(depth_ratio - 1) < 0.01:
                depth_ratio = None
        items, findings = scale(rows, factor, a.to, a.baking, depth_ratio, pan_change, a.time)
        oven_line = oven(a.oven) if a.oven else None
    except (OSError, UnicodeDecodeError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr); return 2
    if a.json:
        print(json.dumps({"factor": factor, "how": how, "units": a.to, "oven": oven_line,
                          "items": [{k: v for k, v in it.items() if k != "notes"} for it in items],
                          "findings": findings}, indent=2, ensure_ascii=False))
    else:
        print(render(a.recipe, factor, how, a.to, items, findings, oven_line))
    return 1 if any(f["severity"] == "HIGH" for f in findings) else 0


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

Hãy đóng vai một Người hướng dẫn Ngắm sao cho Người mới bắt đầu. Bạn giúp những người hoàn toàn mới bắt đầu đi từ chỗ "Tôi chỉ biết mỗi Mặt Trăng" đến việc tự tin tự mình tìm thấy các ngôi sao, hành tinh, chòm sao và Dải Ngân Hà bằng chính đôi mắt và thiết bị họ đang có sẵn. Bạn suy nghĩ như một nhà thiên văn học nghiệp dư kiên nhẫn thường tổ chức các buổi ngắm sao cộng đồng: bạn bắt đầu bằng kỹ năng quan sát bằng mắt thường trước khi dùng đến thiết bị, gắn mọi gợi ý với vị trí, ngày tháng và điều kiện bầu trời của tôi, giải thích mọi thuật ngữ ngay lần đầu tiên bạn sử dụng, và trung thực về những gì có thể nhìn thấy thực tế từ thành phố so với một địa điểm bầu trời tối. Bạn không bao giờ tự bịa ra thời gian mọc chính xác, vị trí hay ngày diễn ra sự kiện; khi yếu tố thời gian là quan trọng, bạn chỉ cho tôi cách kiểm tra thông tin đó trên một ứng dụng mô phỏng bầu trời miễn phí hoặc một nguồn chính thức.

Tình huống của tôi:
- Vị trí và bầu trời: a suburb about 30 km from a large city, some light pollution to the south
- Ngày và giờ tôi dự định quan sát: a weekend evening this month, from about 9 pm to 11 pm
- Thiết bị tôi có: just my eyes, a phone, and an old pair of 8x42 binoculars
- Những gì tôi đã biết: I can find the Moon and maybe the Big Dipper
- Những gì tôi muốn xem: planets, a few bright constellations, the Milky Way, maybe a meteor shower
- Người đi cùng: my partner and a 9-year-old
- Phạm vi di chuyển để đến vùng trời tối hơn: up to 1 hour by car
- Thời tiết và mùa: autumn, nights around 8 C
- Ngân sách cho thiết bị: up to 150 for now

Trước tiên, trong một tin nhắn ngắn gọn, hãy hỏi tôi bất kỳ thông tin quan trọng nào còn thiếu: vĩ độ tương đối hoặc thành phố gần nhất của tôi, liệu tầm nhìn của tôi có bị chắn ở hướng nào không (cây cối, tòa nhà, đèn đường), pha Mặt Trăng vào đêm tôi dự định quan sát nếu tôi biết, liệu tôi có đeo kính không, và liệu có ai trong nhóm gặp khó khăn với thời tiết lạnh hoặc việc thức khuya hay không. Sau đó, hãy hướng dẫn tôi qua các phần sau:

1. **Đêm nay Tóm gọn trong Một Đoạn văn**: một bản tóm tắt ngắn gọn, thực tế về những gì một người mới bắt đầu có thể kỳ vọng nhìn thấy từ vị trí của tôi vào ngày tôi chọn, và một mục tiêu tốt nhất duy nhất để bắt đầu.

2. **Những Thuật ngữ Bầu trời Bạn Sẽ Gặp**: một bảng thuật ngữ ngắn với tên thuật ngữ và giải nghĩa dễ hiểu: chòm sao (constellation), nhóm sao (asterism), cấp sao biểu kiến (magnitude), ô nhiễm ánh sáng (light pollution), thang đo Bortle (Bortle scale), thích nghi bóng tối (dark adaptation), tầm nhìn lệch (averted vision), thiên đỉnh (zenith), đường chân trời (horizon), hoàng đạo (ecliptic), phân biệt hành tinh và ngôi sao (hiện tượng nhấp nháy), lõi Dải Ngân Hà (Milky Way core), tâm điểm mưa sao băng (meteor shower radiant), và trường nhìn (field of view).

3. **Danh sách Kiểm tra Trước Khi Đi**: cách kiểm tra thời tiết và độ che phủ mây, pha Mặt Trăng và lý do Mặt Trăng sáng làm mờ các thiên thể mờ nhạt, bản đồ ô nhiễm ánh sáng, và một ứng dụng mô phỏng bầu trời miễn phí được cài đặt theo vị trí của tôi; cùng với những thứ cần mang theo (đèn ánh sáng đỏ, nhiều lớp áo ấm, chăn hoặc ghế ngả lưng, đồ uống nóng, đồ ăn nhẹ, bản đồ sao in sẵn hoặc trên ứng dụng) và những nguyên tắc an toàn cơ bản ở khu vực trời tối.

4. **30 Phút Đầu tiên của Bạn**: quy trình từng bước: đến nơi, để mắt thích nghi với bóng tối trong 20 đến 30 phút, chỉ sử dụng ánh sáng đỏ, tìm hướng bắc hoặc hướng nam, đo khoảng cách trên bầu trời bằng bàn tay duỗi thẳng (bề ngang ngón tay, nắm đấm và bàn tay xòe rộng), và ba hình mẫu sao neo dễ nhận biết theo mùa của tôi để làm điểm xuất phát.

5. **Lộ trình Nhảy cóc Giữa các Vì sao (Star-Hopping)**: một lộ trình có hướng dẫn đi từ hình mẫu sao neo của tôi đến năm hoặc tám mục tiêu dành cho người mới bắt đầu có thể nhìn thấy trong mùa của tôi, gồm các cột: mục tiêu, phân loại (ngôi sao, hành tinh, chòm sao, cụm sao, thiên hà, tinh vân), cách tìm mục tiêu đó từ mục tiêu trước, quan sát bằng mắt thường hay ống nhòm, và hình dáng thực tế của nó sẽ trông như thế nào. Đánh dấu bất kỳ thông tin nào tôi phải xác nhận lại trên ứng dụng cho ngày cụ thể của mình.

6. **Các Hành tinh và Mặt Trăng**: cách phân biệt một hành tinh với một ngôi sao, cách kiểm tra xem hành tinh nào đang mọc vào đêm nay, hình dáng của từng hành tinh sáng khi nhìn qua ống nhòm, và những pha Mặt Trăng nào là tốt nhất để quan sát các hố va chạm dọc theo đường phân giới sáng tối (terminator line).

7. **Kiến thức Cơ bản về Ống nhòm**: cách lấy nét, cách giữ ống nhòm ổn định (tựa khuỷu tay lên đầu gối, dựa vào xe hơi hoặc ghế), ý nghĩa của thông số 8x42, và những mục tiêu quan sát bằng ống nhòm tốt nhất trong mùa của tôi.

8. **Dải Ngân Hà và Sao băng**: thời điểm và vị trí có thể nhìn thấy Dải Ngân Hà trong mùa của tôi, bầu trời cần tối đến mức nào, cách lên kế hoạch cho một đêm săn mưa sao băng (tâm điểm phát, khung giờ tốt nhất, tư thế nằm ngửa, sự kiên nhẫn), và những gì cần xác nhận trong lịch thiên văn chính thức.

9. **Phiên bản Thân thiện với Trẻ em**: ba hoạt động ngắn giúp một đứa trẻ 9 tuổi luôn hào hứng (kể chuyện về chòm sao, săn tìm vệ tinh, ghi nhật ký quan sát đơn giản kèm hình vẽ), và nên ở lại bao lâu trước khi buổi đi chơi hết vui.

10. **Chụp ảnh bằng Điện thoại Không Gây Nản lòng**: những kỳ vọng thực tế đối với chế độ chụp đêm trên điện thoại, cách sử dụng chân máy nhỏ hoặc bề mặt cố định, hẹn giờ chụp để tránh rung máy, và lý do Mặt Trăng là bức ảnh đầu tiên dễ chụp nhất.

11. **Lời khuyên về Thiết bị theo Ngân sách của Tôi**: liệu có nên mua bất cứ thứ gì ngay bây giờ không, nên mua gì trước tiên (bản đồ sao xoay - planisphere, đèn ánh sáng đỏ, kẹp điện thoại gắn ống nhòm, chân máy nhỏ) và tại sao một chiếc kính thiên văn giá rẻ thường là lựa chọn đầu tiên không tốt; khi nào việc mua một chiếc kính thiên văn nhỏ mới thực sự hợp lý về sau.

12. **Kế hoạch Học tập trong 4 Tuần**: một buổi tối ngắn mỗi tuần, mỗi buổi có một mục tiêu, hai hoặc ba thiên thể cần tìm, và một kỹ năng đơn giản để thực hành, kết thúc bằng việc có thể tự mình tìm được mười thiên thể.

Quy tắc: gắn nhãn dễ, trung bình hoặc khó cho từng mục tiêu tùy theo điều kiện bầu trời của tôi; không bao giờ đưa ra thời gian hoặc ngày tháng cụ thể như một sự thật hiển nhiên mà không nhắc tôi xác nhận lại theo vị trí của mình; tuyệt đối không gợi ý nhìn vào Mặt Trời bằng mắt thường, ống nhòm hoặc điện thoại mà không có bộ lọc Mặt Trời đạt chuẩn; tôn trọng đất tư nhân, nội quy công viên và giữ trật tự tại các điểm ngắm sao chung; sử dụng ngôn từ bình dân, đoạn văn ngắn và bảng biểu ở những chỗ hữu ích. Kết thúc bằng một mục tiêu duy nhất mà tôi nên tìm kiếm đầu tiên vào tối nay và hướng dẫn chính xác cách tìm ra nó.

Hãy đóng vai một nhà thiết kế bối cảnh phong cảnh điện ảnh chuyên viết các bản mô tả cảnh quay (scene brief) sẵn sàng để tạo ảnh tĩnh và tạo chuyển động video. Hãy giúp tôi thiết kế một cảnh quay chủ đạo (hero shot) khắc họa những chiếc cối xay gió truyền thống bằng gạch đứng dọc theo một con kênh vùng đất lấn biển (polder) Hà Lan thẳng tắp, êm đềm lúc bình minh. Cảnh này trước tiên sẽ được tạo ra dưới dạng một bức ảnh tĩnh và sau đó được làm hoạt ảnh thành một đoạn video ngắn sử dụng chính bức ảnh đó làm khung hình đầu tiên. Bản mô tả của bạn phải làm cho bức ảnh tĩnh giàu các yếu tố có thể chuyển động một cách tự nhiên (cánh buồm cối xay gió quay chậm rãi, bóng phản chiếu như gương lấp lánh trên mặt kênh, lau sậy đung đưa nơi mép nước, làn sương sớm là là trên đồng cỏ, ánh bình minh dịu nhẹ) trong khi vẫn giữ cho bố cục tĩnh tại, rõ ràng và dễ làm hoạt ảnh.

Các lựa chọn ban đầu của tôi:
- Cối xay gió: five round tapered brick windmills with dark caps and wooden lattice sails, standing in a row along one bank
- Kênh đào: a long straight canal with still, mirror-like water receding to a vanishing point
- Hai bên bờ: grass and reeds on both sides, a narrow dirt path along a grassy dike on the opposite bank
- Chi tiết tiền cảnh: a small dark wooden rowboat moored at the water's edge
- Phong cảnh: flat green meadows with low mist and a distant line of trees
- Thời gian và ánh sáng: sunrise, soft pink, lilac, and gold sky with a warm glow near the horizon
- Phong cách hình ảnh: photoreal landscape photography, natural colors
- Các từ chỉ cảm xúc (Mood): peaceful, quiet, timeless, fresh

Trước tiên, hãy hỏi tôi trong một tin nhắn ngắn gọn về bất kỳ thông tin nào còn thiếu: vị trí đặt máy quay mà tôi muốn (thấp sát mép nước, ngang tầm mắt người đứng trên bờ, hay hơi cao hơn một chút), các cối xay gió nên đứng ở bờ bên nào, cối xay gió gần nhất nên nằm gần đến mức nào, quầng sáng bình minh nên đặt ở đâu, tôi muốn độ dày của sương mù ra sao, và những thứ cần tránh xuất hiện (con người, người đi xe đạp, thuyền đang chạy, ô tô, tua-bin gió hiện đại, đường dây điện, biển báo, chữ viết, logo, hoặc việc sao chép lại một bức ảnh chụp có thật cụ thể).

Sau đó, hãy lập bản mô tả bao gồm các phần sau:

1. **Tổng quan Cảnh quay (Scene Overview)**: hai hoặc ba câu mô tả địa điểm, thời gian, ánh sáng và cảm xúc của khoảnh khắc đó. Hãy mô tả một khung cảnh vùng đất lấn biển tưởng tượng mang đậm tinh thần Hà Lan, chứ không phải bản sao của một bức ảnh cụ thể hay một địa danh có tên thật.

2. **Cối xay gió (Windmills)**: có bao nhiêu cối xay gió, chúng đứng ở bờ nào, kích thước của chiếc gần nhất trong khung hình, phần thân gạch, chóp mái, các ô cửa sổ nhỏ, cánh buồm mắt cáo và góc nghiêng của cánh buồm, cấu trúc đuôi gỗ hoặc khung cột chống, và cách ánh sáng góc thấp chiếu lên chúng.

3. **Kênh đào và Bóng phản chiếu (Canal and Reflections)**: đường dẫn của con kênh hướng về điểm tụ, độ tĩnh lặng của mặt nước, những hình khối nào được phản chiếu xuống mặt nước, và màu sắc bầu trời hiện lên dưới làn nước ra sao.

4. **Hai bên bờ và Tiền cảnh (Banks and Foreground)**: đám lau sậy và thảm cỏ ở mỗi bên bờ, lối mòn trên đê, chiếc thuyền chèo đang neo đậu cùng sợi dây thừng, và bề mặt chất liệu của những bụi cây gần ống kính nhất.

5. **Phong cảnh và Chiều sâu (Landscape and Depth)**: các lớp chiều sâu không gian tính từ chiếc thuyền và bụi lau sậy ở tiền cảnh đến chiếc cối xay gió gần nhất, hàng cối xay gió lùi dần ở phía sau, những cánh đồng cỏ, cho tới hàng cây xa tắp nơi chân trời, cùng cách làn sương mù làm dịu đi từng lớp cảnh.

6. **Ánh sáng và Bầu trời (Light and Sky)**: vị trí của quầng sáng bình minh, dải chuyển màu (gradient) của bầu trời từ tím tử đinh hương sang hồng rồi vàng kim, hình dáng của những dải mây mỏng, và độ mềm mại của bóng đổ.

7. **Các Chi tiết Hình ảnh Cố định (Fixed Visual Details)**: một danh sách đánh số từ 8 đến 10 chi tiết bắt buộc phải giữ nguyên giống hệt nhau giữa bức ảnh tĩnh và đoạn video (số lượng và bờ đặt cối xay gió, vị trí và góc cánh buồm của cối xay gió gần nhất, đường kẻ của con kênh, vị trí thuyền chèo, lối mòn trên đê, đường chân trời, vị trí quầng sáng, bố cục mây, vị trí máy quay, khung hình).

8. **Sơ đồ Chuyển động (Motion Map)**: một bảng liệt kê mọi yếu tố có thể chuyển động trong video, bao gồm các cột: yếu tố, kiểu chuyển động, hướng, tốc độ (rất chậm, chậm, trung bình), và cường độ chuyển động. Bao gồm cánh buồm của từng cối xay gió, bóng phản chiếu, lau sậy, sương mù, ánh sáng, chiếc thuyền chèo và chuyển động của máy quay. Giữ cho tổng thể chuyển động tinh tế và hợp lý về mặt vật lý, thống nhất một hướng gió duy nhất và tất cả các cánh buồm đều quay cùng một chiều.

9. **Prompt Gốc A - Ảnh Tĩnh Chủ đạo (Prompt Seed A - Hero Still Image)**: một câu lệnh tạo ảnh hoàn chỉnh sẵn sàng sao chép và dán, dài dưới 170 từ cho khung hình ngang rộng tỷ lệ 16:9, nêu bật hình ảnh những chiếc cối xay gió, con kênh và ánh bình minh ngay trong câu đầu tiên, kết thúc bằng cụm từ: không có người, không có chữ, không có logo (no people, no text, no logos).

10. **Prompt Gốc B - Hoạt ảnh từ Ảnh sang Video (Prompt Seed B - Image-to-Video Animation)**: một câu lệnh tạo video hoàn chỉnh sẵn sàng sao chép và dán, dài dưới 120 từ, bắt đầu từ bức ảnh tĩnh chủ đạo làm khung hình đầu tiên, mô tả cánh buồm quay chậm rãi, bóng phản chiếu lấp lánh, lau sậy đung đưa, một chuyển động máy quay đẩy nhẹ (push-in) cực kỳ chậm dọc theo con kênh trong khoảng 6 giây, và yêu cầu giữ nguyên các cối xay gió, con kênh, hai bên bờ, chiếc thuyền cùng khung hình giống hệt như trong ảnh mà không sinh thêm vật thể mới.

Quy tắc: không có người, không có động vật đòi hỏi chuyển động phức tạp, không có phương tiện giao thông hay tua-bin hiện đại; không có chữ viết, biển báo hay logo; không chuyển động máy quay nhanh hoặc cắt cảnh; và không có chuyển động nào vi phạm quy luật vật lý (cánh buồm quay quanh trục giữa mà không bị biến dạng, công trình kiến trúc không bao giờ dịch chuyển, bóng phản chiếu đi theo đúng vật thể phía trên, ánh sáng không bị nhảy đột ngột). Hãy trình bày bằng các đoạn văn ngắn và danh sách gạch đầu dòng.

---
name: meal-prep-storage-and-use-by-planner
description: Lên kế hoạch vị trí bảo quản cho từng khẩu phần nấu sẵn sau một buổi chuẩn bị bữa ăn (meal prep): phần nào để ngăn mát tủ lạnh, phần nào cất vào ngăn đá ngay trong ngày sơ chế, khi nào cần chuyển từng phần xuống ngăn mát để rã đông, và nội dung cần ghi trên nhãn dán, sử dụng mốc thời gian bảo quản ngăn mát và ngăn đá an toàn theo khuyến nghị của USDA. Cảnh báo các bữa ăn được lên lịch quá hạn sử dụng, các thực phẩm không cấp đông được, số khẩu phần thiếu hụt, đồ ăn thừa và tình trạng quá tải ngăn mát. Bao gồm công cụ lập kế hoạch viết bằng thư viện chuẩn Python có hỗ trợ cờ --self-test.
---

# Trình Lập Kế hoạch Bảo quản và Hạn sử dụng Cho Bữa ăn Chuẩn bị Trước (Meal Prep)

Bạn giúp những người nấu ăn theo mẻ vào một ngày trong tuần có thể ăn uống an toàn suốt cả tuần. Dựa trên những món họ đã nấu và thời điểm họ dự định ăn, bạn quyết định khẩu phần nào giữ ở ngăn mát tủ lạnh và khẩu phần nào đưa thẳng vào ngăn đá, lên lịch rã đông và soạn nội dung nhãn dán, để không có món nào trong thực đơn ngày thứ Sáu bị quá hạn bảo quản ngăn mát và không có thứ gì bị lãng phí.

## Các tệp trong kỹ năng này

- `scripts/prep_storage.py` - đọc thông tin mẻ nấu (món ăn, danh mục, số khẩu phần, ngày nấu) và kế hoạch ăn uống, chia khẩu phần giữa ngăn mát và ngăn đá, lên lịch rã đông, viết nội dung nhãn dán cùng kế hoạch chi tiết từng ngày, đồng thời gắn cờ cảnh báo các vấn đề (chỉ sử dụng thư viện chuẩn của Python 3)
- `references/storage-times.md` - thời gian bảo quản ngăn mát và ngăn đá cho 15 danh mục thực phẩm kèm nguồn tham chiếu, và cách xử lý các thực phẩm không có trong danh sách
- `references/cooling-thawing-reheating.md` - làm nguội trong vòng 2 giờ, hộp đựng và nhãn dán, rã đông an toàn, nhiệt độ hâm nóng và nấu chín, cơm và các trường hợp đặc biệt khác
- `templates/prep-week-plan.md` - bản kế hoạch bàn giao lại cho người dùng (bảng bảo quản, lịch từng ngày, nhãn dán, ghi chú)
- `examples/sunday-batch.csv` - một buổi sơ chế ngày Chủ nhật: 7 món, 31 khẩu phần
- `examples/week-plan.csv` - các bữa ăn từ thứ Hai đến thứ Bảy sử dụng các khẩu phần đó

## Quy trình làm việc

### 1. Thu thập thông tin mẻ nấu và kế hoạch ăn
Hỏi xem họ đã nấu hoặc sơ chế những món gì, mỗi món bao nhiêu khẩu phần, ngày nấu, và mỗi khẩu phần dành cho ngày nào, bữa nào. Ánh xạ từng món vào một danh mục (`python3 scripts/prep_storage.py --categories`); khi không chắc chắn, hãy chọn danh mục có thời hạn bảo quản ngắn hơn. Hỏi về không gian ngăn mát tủ lạnh (chứa vừa bao nhiêu hộp) và liệu có món nào bị để ngoài nhiệt độ phòng quá 2 giờ hay không (thực phẩm đó sẽ không được đưa vào kế hoạch mà phải loại bỏ).

### 2. Chạy trình lập kế hoạch
```
python3 scripts/prep_storage.py examples/sunday-batch.csv examples/week-plan.csv --fridge-capacity 16
python3 scripts/prep_storage.py batch.csv plan.csv --json
python3 scripts/prep_storage.py --categories
python3 scripts/prep_storage.py --self-test
```
Ngày 0 là ngày nấu. Các khẩu phần được lên lịch ăn trong khung thời gian an toàn của ngăn mát sẽ được giữ ở ngăn mát; các khẩu phần ăn muộn hơn sẽ được cấp đông ngay trong ngày sơ chế và chuyển xuống ngăn mát vào buổi tối hôm trước ngày ăn. Sử dụng các cột tùy chọn `fridge_days` và `freezer_months` cho những thực phẩm không có trong bảng (`freezer_months` bằng 0 = không cấp đông). Mã thoát (exit code) 1 nghĩa là có phát hiện mức HIGH (một khẩu phần sẽ bị ăn quá hạn sử dụng hoặc trước khi được nấu chín), mã thoát 2 nghĩa là dữ liệu đầu vào không hợp lệ.

### 3. Điều chỉnh kế hoạch
Giải quyết mọi phát hiện cảnh báo (xem `references/storage-times.md`):
- PAST_USE_BY: đẩy bữa ăn đó lên sớm hơn, đổi chỗ với một món có thể cấp đông, hoặc nấu mới món đó vào giữa tuần.
- SHORTFALL: nấu thêm hoặc đổi món cho bữa đó; SURPLUS_NO_FREEZE: ăn sớm hơn hoặc nấu ít lại vào lần sau.
- FRIDGE_FULL: cấp đông thêm khẩu phần ngay trong ngày sơ chế, gộp chung các khẩu phần, hoặc chia làm hai buổi sơ chế mỗi tuần.
Chạy lại chương trình cho đến khi không còn phát hiện mức HIGH nào.

### 4. Bàn giao kết quả
Điền vào mẫu `templates/prep-week-plan.md`: bảng bảo quản, các việc cần làm trong ngày sơ chế (làm nguội, chia phần, dán nhãn, cất ngăn mát hoặc ngăn đá), danh sách theo từng ngày bao gồm cả lời nhắc "chuyển xuống ngăn mát" vào buổi tối, nội dung các nhãn cần viết, và các ghi chú an toàn từ `references/cooling-thawing-reheating.md` áp dụng cho mẻ nấu này.

## Ví dụ kết quả
Mẻ nấu Chủ nhật 2026-11-01: cơm tô burrito gà (chicken burrito bowls), cơm trắng và súp thịt gà tây hầm ớt (turkey chili) giữ lại mỗi món 3 khẩu phần ở ngăn mát (ăn trước thứ Năm 11-05); 2 phần burrito, 2 phần cơm và 3 phần chili đưa vào ngăn đá ngay Chủ nhật, chuyển xuống ngăn mát vào tối thứ Năm và tối thứ Sáu. Cá hồi sống ướp sẵn (khung an toàn 2 ngày) được cấp đông sống vào Chủ nhật, chuyển xuống ngăn mát vào tối thứ Ba, và nấu chín vào thứ Tư tới nhiệt độ tâm 145 F / 63 C. Món salad trứng vào thứ Sáu rơi vào ngày thứ 5 mà salad trứng lại không cấp đông tốt được: cảnh báo HIGH PAST_USE_BY, vì vậy hãy chuyển bữa trưa đó sang thứ Tư hoặc thứ Năm hoặc làm mới trong ngày. Hai quả trứng luộc chín chưa có lịch ăn (ăn trước Chủ nhật 11-08), một khẩu phần chili làm phần dự phòng trong ngăn đá, và tổng cộng 22 hộp không thể xếp vừa ngăn tủ lạnh chỉ chứa được 16 hộp vào ngày Chủ nhật.

## Quy tắc

- Luôn sử dụng mốc bảo thủ (ngắn nhất) của mọi khoảng thời gian và nêu rõ điều đó; khi nghi ngờ, hãy vứt bỏ.
- Tính ngày nấu là ngày 0; thực phẩm có hạn 4 ngày nấu vào Chủ nhật phải được ăn hết muộn nhất vào thứ Năm.
- Thời gian bảo quản ngăn đá là vì chất lượng món ăn, không phải vì an toàn; thời gian bảo quản ngăn mát là vì an toàn thực phẩm. Tuyệt đối không kéo dài thời gian để ngăn mát chỉ vì thức ăn "trông vẫn ổn".
- Rã đông trong ngăn mát tủ lạnh, trong nước lạnh hoặc bằng lò vi sóng, tuyệt đối không rã đông trên mặt bàn bếp ở nhiệt độ phòng; ăn thức ăn chín đã rã đông trong vòng 3-4 ngày và không tính những ngày đã nằm ở ngăn mát trước khi cấp đông như đồ mới nấu.
- Thực phẩm sống phải có hạn "nấu trước ngày" (cook-by date) và nhiệt độ tâm an toàn khi nấu chín, chứ không phải ghi chú hâm nóng lại.
- Đây là hướng dẫn an toàn thực phẩm chung, không phải lời khuyên y tế; đối với phụ nữ mang thai, trẻ sơ sinh, người cao tuổi hoặc người có hệ miễn dịch suy yếu, hãy tuân theo hướng dẫn y tế địa phương nghiêm ngặt hơn.
FILE:references/storage-times.md
# Thời gian bảo quản ngăn mát và ngăn đá

Các giá trị được sử dụng bởi `scripts/prep_storage.py`. Ngăn mát ở mức 40 F / 4 C hoặc lạnh hơn, ngăn đá ở mức 0 F / -18 C. Ngày 0 là ngày thực phẩm được nấu chín (hoặc đối với đồ sống là ngày sơ chế/tẩm ướp sau khi mua về).

Nguồn: "Bảng Bảo quản Thực phẩm Lạnh" (Cold Food Storage Chart) của USDA FSIS / FoodSafety.gov và ứng dụng USDA FoodKeeper. Ở những mục có khoảng thời gian dao động, trình lập kế hoạch luôn chọn thời gian ngăn mát ngắn hơn.

| Danh mục | Ví dụ | Ngăn mát (theo bảng) | Giá trị dùng | Ngăn đá (chất lượng) | Giá trị dùng |
|---|---|---|---|---|---|
| cooked_meat | thịt bò nướng, thịt heo xé, thịt viên, thịt băm nấu chín | 3-4 ngày | 4 | 2-6 tháng | 3 |
| cooked_poultry | thịt gà xé, ức gà tây, đùi gà nấu chín | 3-4 ngày | 4 | 2-6 tháng | 3 |
| soup_stew | súp, món hầm, chili, cà ri, đậu hầm dal | 3-4 ngày | 4 | 2-3 tháng | 3 |
| casserole | lasagna, enchiladas, món đút lò, bánh thịt hầm shepherd's pie | 3-4 ngày | 4 | 2-3 tháng | 3 |
| cooked_grains | cơm, mì ống, hạt diêm mạch (quinoa), couscous | 3-5 ngày | 4 | 1-2 tháng | 2 |
| cooked_vegetables | rau củ nướng hoặc hấp, các loại đậu đã nấu chín | 3-4 ngày | 4 | khoảng 2 tháng | 2 |
| cooked_fish | cá hồi nướng, tôm đã nấu chín | 3-4 ngày | 3 | khoảng 3 tháng | 3 |
| pizza | bánh pizza, bánh nướng mặn, lát bánh quiche | 3-4 ngày | 4 | 1-2 tháng | 2 |
| deli_salad | salad trứng, gà, cá ngừ, giăm bông, mì ống trộn | 3-5 ngày | 4 | không cấp đông tốt | - |
| hard_boiled_eggs | đã bóc vỏ hoặc chưa bóc vỏ | 1 tuần | 7 | không cấp đông | - |
| cut_raw_vegetables | cà rốt cắt thanh, hành tây thái nhỏ, ớt chuông cắt | khoảng 3-5 ngày (chất lượng) | 4 | cần chần trước; không đưa vào kế hoạch cấp đông | - |
| raw_ground_meat | thịt bò, gà tây, heo xay sống, thịt băm ướp sống | 1-2 ngày | 2 | 3-4 tháng | 3 |
| raw_poultry | thịt gà chặt miếng, đùi gà ướp sống | 1-2 ngày | 2 | 9 tháng (thịt miếng) | 9 |
| raw_steak_chops | bít tết, sườn cốt lết, thịt tảng nướng sống | 3-5 ngày | 4 | 4-12 tháng | 4 |
| raw_fish | phi lê cá hồi, cá thịt trắng sống | 1-2 ngày | 2 | 2-3 tháng (cá béo), 6-8 tháng (cá nạc) | 2 |

## Các thực phẩm không cấp đông tốt
Các món salad trộn sốt mayonnaise, lòng trắng trứng luộc chín (bị dai như cao su), rau xà lách sống, dưa chuột, các loại sốt kem dễ bị tách nước, lớp vỏ chiên tẩm bột (bị ỉu nhũn), mì ống đã luộc chín ngâm trong nước sốt loãng (bị bở nát). Hãy cấp đông riêng phần nước sốt và phần mì ống khi có thể.

## Món ăn hỗn hợp
Áp dụng thời hạn của nguyên liệu có hạn sử dụng ngắn nhất: một tô cơm cá được xếp vào nhóm `cooked_fish` (3 ngày), chứ không phải `cooked_grains` (4 ngày). Nước sốt và nước trộn bảo quản riêng sẽ tính theo nhãn của chính chúng; các loại sốt mua sẵn đã mở nắp tính theo hướng dẫn trên lọ.

## Thực phẩm không có trong danh sách
Thêm cột `fridge_days` và `freezer_months` vào tệp BATCH.csv dựa theo dữ liệu từ FoodKeeper hoặc nhãn sản phẩm. Nếu không có nguồn tra cứu nào, hãy áp dụng 3 ngày ngăn mát và không cấp đông.

## Cách đếm ngày
- Nấu vào Chủ nhật, hạn 4 ngày: Thứ Hai (1), Thứ Ba (2), Thứ Tư (3), Thứ Năm (4) là ngày cuối cùng được phép ăn.
- Thực phẩm được cấp đông ngay trong ngày sơ chế và rã đông trong ngăn mát: ăn trong vòng 3-4 ngày kể từ khi rã đông (trình lập kế hoạch xếp lịch chuyển từ ngăn đá xuống ngăn mát vào buổi tối hôm trước).
- Thực phẩm đến ngày thứ 3 mới đem cấp đông thì chỉ còn khoảng 1 ngày ngăn mát sau khi rã đông; hãy cấp đông sớm, lý tưởng nhất là ngay trong ngày nấu.

## Cấp đông lại
Thực phẩm rã đông trong ngăn mát tủ lạnh có thể cấp đông lại mà không cần nấu chín (nhưng chất lượng sẽ giảm). Thực phẩm rã đông bằng nước lạnh hoặc lò vi sóng bắt buộc phải được nấu chín trước khi cấp đông lại.
FILE:references/cooling-thawing-reheating.md
# Làm nguội, đóng gói, rã đông và hâm nóng

## Làm nguội sau khi nấu (quy tắc 2 giờ)
- Đưa thực phẩm đã nấu vào ngăn mát hoặc ngăn đá trong vòng 2 giờ sau khi nấu (1 giờ nếu nhiệt độ phòng cao hơn 90 F / 32 C).
- Vi khuẩn sinh sôi nhanh nhất trong khoảng từ 40 F đến 140 F (4-60 C). Các nồi lớn nguội quá chậm: hãy chia nhỏ vào các hộp nông lòng (sâu khoảng 2 in / 5 cm) hoặc ngâm nồi vào chậu nước đá kết hợp khuấy đều để hạ nhiệt.
- Thức ăn còn nóng có thể đưa thẳng vào tủ lạnh; hãy hé nhẹ nắp hộp cho đến khi hết bốc hơi nóng, và không xếp chồng các hộp còn nóng lên nhau.
- Cơm và các thực phẩm giàu tinh bột khác: cần làm nguội và cất tủ lạnh thật nhanh. Bào tử vi khuẩn *Bacillus cereus* sống sót qua quá trình nấu chín và tiết ra độc tố khi cơm để ở nhiệt độ ấm; việc hâm nóng lại không tiêu diệt được độc tố này.

## Đóng gói và dán nhãn
- Chia mỗi khẩu phần vào một hộp riêng giúp kế hoạch vận hành trơn tru: bạn chỉ rã đông đúng phần mình sẽ ăn.
- Ngăn đá: dùng túi zip trữ đông ép dẹt (giúp cấp đông và rã đông nhanh), hoặc hộp cứng có chừa khoảng trống 1/2 in (khoảng 1.2 cm) phía trên cho chất lỏng giãn nở.
- Dán nhãn mọi hộp đựng: tên món, ngày nấu, "ăn trước ngày / eat by" (ngăn mát) hoặc "tốt nhất trước ngày / best by" (ngăn đá), hướng dẫn hâm nóng hoặc nấu chín. Chỉ cần băng dính giấy và bút dạ là đủ.
- Để các thực phẩm sống ở ngăn kệ dưới cùng, bên dưới các thực phẩm ăn liền/đã nấu chín.

## Rã đông
| Phương pháp | Cách thực hiện | Sau khi rã đông |
|---|---|---|
| Ngăn mát (tốt nhất) | chuyển xuống từ tối hôm trước; khối thực phẩm lớn hoặc đặc cần 24 giờ cho mỗi 5 lb / 2.3 kg | thức ăn chín dùng trong 3-4 ngày; thịt xay, gia cầm, cá sống dùng trong 1-2 ngày |
| Nước lạnh | cho vào túi kín ngâm trong nước lạnh, thay nước mỗi 30 phút | nấu chín hoặc hâm nóng ngay lập tức |
| Lò vi sóng | chế độ rã đông (defrost) | nấu chín hoặc hâm nóng ngay lập tức |
| Mặt bàn bếp (nhiệt độ phòng) | tuyệt đối không bao giờ | - |
Các món súp và món hầm có thể đem hâm nóng trực tiếp từ trạng thái đông đá trong nồi.

## Nhiệt độ hâm nóng và nấu chín (nhiệt độ tâm thực phẩm)
| Thực phẩm | Nhiệt độ |
|---|---|
| Đồ ăn thừa và món đút lò (casseroles), hâm nóng lại | 165 F / 74 C |
| Súp, nước sốt, nước thịt (gravies) | đun sôi sùng sục |
| Gia cầm sống | 165 F / 74 C |
| Thịt bò, heo, cừu xay sống | 160 F / 71 C |
| Bít tết, sườn cốt lết, thịt tảng sống | 145 F / 63 C cộng thêm 3 phút nghỉ |
| Cá sống | 145 F / 63 C hoặc cho đến khi thịt cá tơi thành từng thớ và chuyển màu đục |
Lò vi sóng: đậy nắp, đảo đều ở giữa chừng, để nghỉ 1-2 phút sau khi quay, và kiểm tra phần giữa món ăn bằng nhiệt kế thực phẩm.

## Cơm hộp mang đi làm
Sử dụng túi giữ nhiệt có đặt túi đá lạnh (ice pack); hâm nóng tại nơi làm việc cho đến khi bốc khói nghi ngút. Thức ăn để ở nhiệt độ phòng quá 2 giờ phải vứt bỏ, không cất ngược lại vào tủ lạnh.

## Dấu hiệu cảm quan không phải là phép thử an toàn
Vi khuẩn gây hỏng thức ăn (tạo mùi hôi, nhớt) và vi khuẩn gây bệnh (gây ngộ độc) là hai nhóm khác nhau; thức ăn có thể trông vẫn đẹp và thơm tho bình thường nhưng vẫn không còn an toàn. Hãy tuân theo ngày tháng trên nhãn, đừng tin vào chiếc mũi.

## Ai cần tuân thủ nghiêm ngặt hơn
Phụ nữ mang thai, trẻ sơ sinh, người cao tuổi và bất kỳ ai có hệ miễn dịch suy yếu: ăn đồ nấu sẵn sớm hơn, hâm nóng tới mức bốc khói nghi ngút, tránh ăn các món salad trộn sẵn (deli salads) sau ngày thứ 2, và tuân thủ hướng dẫn y tế tại địa phương.
FILE:templates/prep-week-plan.md
# Kế hoạch chuẩn bị bữa ăn (Meal prep): tuần lễ từ <2026-11-02>

**Ngày sơ chế:** <Chủ nhật 2026-11-01>   **Số người ăn:** <2 người lớn>   **Sức chứa ngăn mát:** <16 hộp>
**Trạng thái:** <OK / Đã dời 1 bữa ăn để tránh lỗi PAST_USE_BY>

## Kế hoạch bảo quản
| Món ăn | Danh mục | Số khẩu phần | Ngăn mát | Ngăn đá | Ăn trước (ngăn mát) | Tốt nhất trước (ngăn đá) |
|---|---|---|---|---|---|---|
| <Turkey chili> | <soup_stew> | <6> | <3> | <3> | <Thứ Năm 11-05> | <2027-02-01> |

## Danh mục công việc ngày sơ chế
- [ ] Làm nguội tất cả trong hộp nông lòng; đưa vào ngăn mát hoặc ngăn đá trong vòng 2 giờ
- [ ] Chia khẩu phần: mỗi hộp một khẩu phần
- [ ] Cấp đông ngăn đá: <chili x3, burrito bowls x2, cơm x2, cá hồi x2 (sống, ép dẹt)>
- [ ] Cất ngăn mát: <...>
- [ ] Dán nhãn mọi hộp đựng (tên món, ngày nấu, ăn trước / tốt nhất trước, nhiệt độ hâm nóng hoặc nấu chín)

## Lịch trình từng ngày
| Ngày | Bữa sáng | Bữa trưa | Bữa tối | Buổi tối: chuyển xuống ngăn mát |
|---|---|---|---|---|
| <Thứ Hai 11-02> | <trứng luộc chín x2> | <burrito bowl + cơm> | <turkey chili x2> | <-> |

## Nhãn dán
| Hộp đựng | Nội dung nhãn dán |
|---|---|
| <Turkey chili (ngăn mát)> | <TURKEY CHILI - nấu CN 11/01 - ăn trước T5 11/05 - hâm nóng tới 165 F> |

## Các thay đổi đã thực hiện
- <Dời bữa trưa món salad trứng từ thứ Sáu sang thứ Tư (ngày thứ 5 vượt quá giới hạn 4 ngày)>

## Phần dự phòng và đồ ăn thừa
- <1 khẩu phần chili trong ngăn đá, dùng tốt nhất trước 2027-02-01>

## Ghi chú an toàn cho mẻ nấu này
- <cơm: làm nguội nhanh, chỉ hâm nóng một lần, nóng bốc khói>
- <cá hồi: rã đông trong ngăn mát vào tối thứ Ba, nấu chín vào thứ Tư tới 145 F / 63 C>
FILE:examples/sunday-batch.csv
item,category,portions,cooked_on
Chicken burrito bowl,cooked_poultry,5,2026-11-01
Cilantro lime rice,cooked_grains,5,2026-11-01
Turkey chili,soup_stew,6,2026-11-01
Egg salad,deli_salad,3,2026-11-01
Hard-boiled eggs,hard_boiled_eggs,6,2026-11-01
Roasted vegetables,cooked_vegetables,4,2026-11-01
Miso salmon (raw marinated),raw_fish,2,2026-11-01
FILE:examples/week-plan.csv
date,meal,item,portions
2026-11-02,breakfast,Hard-boiled eggs,2
2026-11-02,lunch,Chicken burrito bowl,1
2026-11-02,lunch,Cilantro lime rice,1
2026-11-02,dinner,Turkey chili,2
2026-11-03,lunch,Egg salad,1
2026-11-03,dinner,Chicken burrito bowl,1
2026-11-03,dinner,Cilantro lime rice,1
2026-11-04,breakfast,Hard-boiled eggs,2
2026-11-04,lunch,Turkey chili,1
2026-11-04,dinner,Miso salmon (raw marinated),2
2026-11-04,dinner,Roasted vegetables,2
2026-11-05,lunch,Chicken burrito bowl,1
2026-11-05,lunch,Cilantro lime rice,1
2026-11-05,dinner,Roasted vegetables,2
2026-11-06,lunch,Egg salad,2
2026-11-06,dinner,Chicken burrito bowl,2
2026-11-06,dinner,Cilantro lime rice,2
2026-11-07,lunch,Turkey chili,2
FILE:scripts/prep_storage.py
#!/usr/bin/env python3
"""Meal prep storage and use-by planner (Python 3 standard library only).

Takes a batch-cooking session (what was cooked, how many portions, when) and the
week's eating plan, and decides for every portion whether it stays in the fridge or
goes into the freezer on prep day, when to move frozen portions to the fridge to thaw,
and what to write on each label. Flags portions planned after their fridge window that
cannot be frozen, plans that need more portions than were cooked, portions planned
before they are cooked, leftovers with no plan, and a fridge that holds more
containers than it has room for.

Fridge and freezer times are conservative values from the USDA/FoodSafety.gov cold
storage chart and the FoodKeeper app (see references/storage-times.md). Day 0 is the
cooking day; a 4-day item cooked on Sunday must be eaten by Thursday. Freezer times
are for quality: food kept frozen at 0 F / -18 C stays safe, it just gets worse.

Usage:
  python3 prep_storage.py BATCH.csv PLAN.csv [--fridge-capacity 12] [--json]
  python3 prep_storage.py --categories
  python3 prep_storage.py --self-test
BATCH.csv columns: item,category,portions,cooked_on[,fridge_days,freezer_months]
PLAN.csv  columns: date,meal,item,portions   (dates as YYYY-MM-DD)
Exit codes: 0 = plan is safe, 1 = at least one HIGH finding, 2 = bad input.
"""
import argparse, csv, datetime as dt, io, json, sys

SEV_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
MEAL_ORDER = {"prep": 0, "breakfast": 1, "lunch": 2, "snack": 3, "dinner": 4, "evening": 5}
SERVE_COLD = {"deli_salad", "hard_boiled_eggs", "cut_raw_vegetables"}
# safe minimum internal temperatures for raw categories (cook on the planned day)
COOK_TEMP = {"raw_ground_meat": "160 F / 71 C", "raw_poultry": "165 F / 74 C",
             "raw_steak_chops": "145 F / 63 C plus 3 min rest", "raw_fish": "145 F / 63 C"}
# category: (fridge_days, freezer_months or None if it does not freeze well, note)
CATEGORIES = {
    "cooked_meat":       (4, 3, "cooked beef, pork, lamb; chart 3-4 days / 2-6 months"),
    "cooked_poultry":    (4, 3, "cooked chicken, turkey; chart 3-4 days / 2-6 months"),
    "soup_stew":         (4, 3, "soups, stews, chili, curries; chart 3-4 days / 2-3 months"),
    "casserole":         (4, 3, "casseroles, lasagna, bakes; 3-4 days / 2-3 months"),
    "cooked_grains":     (4, 2, "cooked rice, pasta, quinoa; cool fast; 3-5 days / 1-2 months"),
    "cooked_vegetables": (4, 2, "roasted or steamed vegetables, cooked beans; 3-4 days used"),
    "cooked_fish":       (3, 3, "cooked fish and seafood; 3-4 days, 3 used"),
    "pizza":             (4, 2, "pizza, savory pies; chart 3-4 days / 1-2 months"),
    "deli_salad":        (4, None, "egg, chicken, tuna, pasta salads; chart 3-5 days, does not freeze well"),
    "hard_boiled_eggs":  (7, None, "hard-cooked eggs; chart 1 week, do not freeze"),
    "cut_raw_vegetables": (4, None, "washed and cut raw vegetables; quality guide 3-5 days; blanch before freezing"),
    "raw_ground_meat":   (2, 3, "raw ground meat or marinated mince; chart 1-2 days / 3-4 months"),
    "raw_poultry":       (2, 9, "raw chicken or turkey pieces, marinated; chart 1-2 days / 9 months"),
    "raw_steak_chops":   (4, 4, "raw steaks, chops, roasts; chart 3-5 days / 4-12 months"),
    "raw_fish":          (2, 2, "raw fish; chart 1-2 days / 2-3 months fatty, 6-8 months lean"),
}


class InputError(Exception):
    pass


def parse_date(s, where):
    try:
        return dt.date.fromisoformat(s.strip())
    except ValueError:
        raise InputError(f"{where}: date '{s}' is not YYYY-MM-DD")


def parse_int(s, where, minimum=0):
    try:
        v = int(str(s).strip())
    except ValueError:
        raise InputError(f"{where}: '{s}' is not a whole number")
    if v < minimum:
        raise InputError(f"{where}: {v} must be at least {minimum}")
    return v


def read_rows(text, required, name):
    rows = list(csv.DictReader(io.StringIO(text.lstrip("\ufeff"))))
    if not rows:
        raise InputError(f"{name} has no rows")
    missing = [c for c in required if c not in rows[0]]
    if missing:
        raise InputError(f"{name} is missing column(s): {', '.join(missing)}")
    return [{k.strip(): (v or "").strip() for k, v in r.items() if k} for r in rows if any((v or "").strip() for v in r.values())]


def load_batch(text):
    items = {}
    for i, r in enumerate(read_rows(text, ["item", "category", "portions", "cooked_on"], "BATCH"), 2):
        where = f"BATCH line {i}"
        cat = r["category"].lower()
        if cat not in CATEGORIES and not r.get("fridge_days"):
            raise InputError(f"{where}: unknown category '{r['category']}' (see --categories, or give fridge_days/freezer_months)")
        fd, fm, note = CATEGORIES.get(cat, (None, None, "custom"))
        if r.get("fridge_days"):
            fd = parse_int(r["fridge_days"], where, 1)
        if r.get("freezer_months") is not None and r.get("freezer_months") != "":
            fm = parse_int(r["freezer_months"], where, 0) or None
        name = r["item"]
        if name.lower() in items:
            raise InputError(f"{where}: item '{name}' listed twice; give each batch its own name")
        items[name.lower()] = {"item": name, "category": cat, "portions": parse_int(r["portions"], where, 1),
                               "cooked_on": parse_date(r["cooked_on"], where), "fridge_days": fd,
                               "freezer_months": fm, "note": note}
    return items


def load_plan(text, items):
    plan = []
    for i, r in enumerate(read_rows(text, ["date", "meal", "item", "portions"], "PLAN"), 2):
        where = f"PLAN line {i}"
        key = r["item"].lower()
        if key not in items:
            raise InputError(f"{where}: item '{r['item']}' is not in BATCH")
        plan.append({"date": parse_date(r["date"], where), "meal": r["meal"], "item": key,
                     "portions": parse_int(r["portions"], where, 1)})
    plan.sort(key=lambda p: p["date"])
    return plan


def add_months(d, months):
    y, m = divmod(d.month - 1 + months, 12)
    y, m = d.year + y, m + 1
    last = (dt.date(y + (m == 12), m % 12 + 1, 1) - dt.timedelta(days=1)).day
    return dt.date(y, m, min(d.day, last))


def plan_storage(items, plan, fridge_capacity=None):
    findings, timeline, labels = [], {}, []

    def add(sev, code, item, detail):
        findings.append({"severity": sev, "code": code, "item": item, "detail": detail})

    def ev(day, slot, text):
        timeline.setdefault(day, []).append((MEAL_ORDER.get(slot.lower(), 3), text))

    summary = {}
    for key, it in items.items():
        cooked, fd, fm = it["cooked_on"], it["fridge_days"], it["freezer_months"]
        eat_by = cooked + dt.timedelta(days=fd)
        best_by = add_months(cooked, fm) if fm else None
        left = it["portions"]
        fridge_n = freeze_n = 0
        uses = [p for p in plan if p["item"] == key]
        raw = it["category"] in COOK_TEMP
        how = (f"cook to {COOK_TEMP[it['category']]}" if raw else
               "serve cold" if it["category"] in SERVE_COLD else "reheat to 165 F / 74 C")
        for p in uses:
            n = min(p["portions"], left)
            short = p["portions"] - n
            if short:
                add("MEDIUM", "SHORTFALL", it["item"], f"{p['date']} {p['meal']} needs {p['portions']} portion(s), only {n} left; cook more or swap the meal")
            if n == 0:
                continue
            left -= n
            if p["date"] < cooked:
                add("HIGH", "BEFORE_COOKED", it["item"], f"{p['date']} {p['meal']} is before the cooking day {cooked}")
                continue
            if p["date"] <= eat_by:
                fridge_n += n
                ev(p["date"], p["meal"], f"{p['meal']}: {it['item']} x{n} (fridge; {how})")
            elif fm:
                freeze_n += n
                thaw = p["date"] - dt.timedelta(days=1)
                ev(p["date"], p["meal"], f"{p['meal']}: {it['item']} x{n} (thawed; {how})")
                ev(thaw, "evening", f"evening: move {it['item']} x{n} from freezer to fridge for {p['date']} {p['meal']}")
                if best_by and p["date"] > best_by:
                    add("LOW", "PAST_FREEZER_QUALITY", it["item"], f"{p['date']} is after the best-quality date {best_by} (safe, but drier and blander)")
            else:
                fridge_n += n
                add("HIGH", "PAST_USE_BY", it["item"],
                    f"{p['date']} {p['meal']} is {(p['date'] - cooked).days} days after cooking; fridge limit is {fd} days (eat by {eat_by}) and it does not freeze well. Move the meal earlier or cook it fresh.")
        if left:
            if fm:
                freeze_n += left
                add("INFO", "SURPLUS_FROZEN", it["item"], f"{left} unplanned portion(s) go in the freezer on {cooked}; best by {best_by}")
            else:
                add("MEDIUM", "SURPLUS_NO_FREEZE", it["item"], f"{left} unplanned portion(s) do not freeze well: eat by {eat_by} or cook less next time")
                fridge_n += left
        if freeze_n:
            ev(cooked, "prep", f"freeze {it['item']} x{freeze_n} " + ("raw, flat in freezer bags" if raw else "once cooled (fridge or freezer within 2 hours of cooking)"))
        if fridge_n:
            ev(cooked, "prep", f"fridge {it['item']} x{fridge_n} ({'cook' if raw else 'eat'} by {eat_by})")
        labels.append({"item": it["item"], "cooked_on": str(cooked),
                       "fridge": f"x{fridge_n}, eat by {eat_by}" if fridge_n else "-",
                       "freezer": f"x{freeze_n}, best by {best_by}" if freeze_n else "-"})
        summary[it["item"]] = {"category": it["category"], "portions": it["portions"], "fridge": fridge_n,
                               "freezer": freeze_n, "eat_by": str(eat_by), "best_by": str(best_by) if best_by else None,
                               "fridge_days": fd, "freezer_months": fm}

    if fridge_capacity:
        days = sorted(set([it["cooked_on"] for it in items.values()] + [p["date"] for p in plan]))
        if days:
            d = days[0]
            worst = (0, None)
            while d <= days[-1]:
                count = _fridge_count(items, plan, summary, d)
                if count > worst[0]:
                    worst = (count, d)
                d += dt.timedelta(days=1)
            if worst[0] > fridge_capacity:
                add("MEDIUM", "FRIDGE_FULL", "-", f"{worst[0]} containers in the fridge on {worst[1]}, capacity {fridge_capacity}: freeze more on prep day or use bigger containers")
    findings.sort(key=lambda f: (SEV_ORDER[f["severity"]], f["item"], f["code"]))
    return {"summary": summary, "timeline": {str(k): [t for _, t in sorted(v, key=lambda x: x[0])] for k, v in sorted(timeline.items())},
            "labels": labels, "findings": findings}


def _fridge_count(items, plan, summary, day):
    """Containers in the fridge at the end of `day` (one portion = one container)."""
    total = 0
    for key, it in items.items():
        if day < it["cooked_on"]:
            continue
        eat_by = it["cooked_on"] + dt.timedelta(days=it["fridge_days"])
        fridge_left = summary[it["item"]]["fridge"]
        for p in plan:
            if p["item"] == key and p["date"] <= day and it["cooked_on"] <= p["date"] <= eat_by:
                fridge_left -= p["portions"]
        if day <= eat_by:
            total += max(fridge_left, 0)
        for p in plan:  # thawing portions moved in the evening before
            if p["item"] == key and p["date"] > eat_by and p["date"] - dt.timedelta(days=1) == day and it["freezer_months"]:
                total += p["portions"]
    return total


def render_md(res):
    out = ["# Meal prep storage plan", "", "| Item | Category | Portions | Fridge | Freezer | Eat by (fridge) | Best by (freezer) |",
           "|---|---|---|---|---|---|---|"]
    for name, s in res["summary"].items():
        out.append(f"| {name} | {s['category']} | {s['portions']} | {s['fridge']} | {s['freezer']} | {s['eat_by']} | {s['best_by'] or 'do not freeze'} |")
    out += ["", "## Day by day", ""]
    for day, evs in res["timeline"].items():
        d = dt.date.fromisoformat(day)
        out.append(f"- **{d.strftime('%a')} {day}**: " + "; ".join(evs))
    out += ["", "## Labels", "", "| Item | Cooked | Fridge | Freezer |", "|---|---|---|---|"]
    out += [f"| {l['item']} | {l['cooked_on']} | {l['fridge']} | {l['freezer']} |" for l in res["labels"]]
    out += ["", "## Findings", ""]
    if res["findings"]:
        out += ["| Severity | Code | Item | Detail |", "|---|---|---|---|"]
        out += [f"| {f['severity']} | {f['code']} | {f['item']} | {f['detail']} |" for f in res["findings"]]
    else:
        out.append("No problems: every planned portion is eaten inside its fridge window or thawed from the freezer.")
    out += ["", "Cool food within 2 hours in shallow containers, keep the fridge at 40 F / 4 C or colder and the freezer at 0 F / -18 C. When in doubt, throw it out."]
    return "\n".join(out)


# ---------------------------------------------------------------- self-test
def self_test():
    B = "item,category,portions,cooked_on\nChili,soup_stew,5,2026-11-01\nEgg salad,deli_salad,3,2026-11-01\nRice,cooked_grains,4,2026-11-01\n"
    P = ("date,meal,item,portions\n2026-11-02,lunch,Chili,1\n2026-11-03,lunch,Chili,1\n2026-11-06,dinner,Chili,2\n"
         "2026-11-02,lunch,Egg salad,1\n2026-11-04,lunch,Egg salad,1\n2026-11-03,dinner,Rice,2\n")
    def run(b=B, p=P, cap=None):
        items = load_batch(b)
        return plan_storage(items, load_plan(p, items), cap)
    codes = lambda r: [f["code"] for f in r["findings"]]
    cases = [
        ("categories table sane", lambda: all(v[0] >= 1 for v in CATEGORIES.values())),
        ("add_months end of month", lambda: add_months(dt.date(2026, 1, 31), 1) == dt.date(2026, 2, 28)),
        ("add_months over year", lambda: add_months(dt.date(2026, 11, 15), 3) == dt.date(2027, 2, 15)),
        ("fridge window day 0 = cooking day", lambda: run()["summary"]["Chili"]["eat_by"] == "2026-11-05"),
        ("chili day 5 goes to freezer", lambda: run()["summary"]["Chili"]["freezer"] == 3),
        ("chili days 1-2 stay in fridge", lambda: run()["summary"]["Chili"]["fridge"] == 2),
        ("thaw move the evening before", lambda: any("move Chili x2" in e for e in run()["timeline"]["2026-11-05"])),
        ("surplus chili frozen INFO", lambda: "SURPLUS_FROZEN" in codes(run())),
        ("egg salad inside window ok", lambda: "PAST_USE_BY" not in codes(run())),
        ("egg salad day 5 is PAST_USE_BY", lambda: "PAST_USE_BY" in codes(run(p=P.replace("2026-11-04,lunch,Egg", "2026-11-06,lunch,Egg")))),
        ("egg salad surplus no freeze", lambda: "SURPLUS_NO_FREEZE" in codes(run())),
        ("shortfall", lambda: "SHORTFALL" in codes(run(p=P + "2026-11-04,dinner,Rice,3\n"))),
        ("before cooked", lambda: "BEFORE_COOKED" in codes(run(p=P + "2026-10-31,dinner,Rice,1\n"))),
        ("past freezer quality", lambda: "PAST_FREEZER_QUALITY" in codes(run(p=P + "2027-03-01,dinner,Rice,1\n"))),
        ("override fridge_days column", lambda: run(b="item,category,portions,cooked_on,fridge_days,freezer_months\nSoup,custom,2,2026-11-01,2,0\n",
                                                   p="date,meal,item,portions\n2026-11-04,lunch,Soup,1\n")["findings"][0]["code"] == "PAST_USE_BY"),
        ("unknown category error", lambda: _raises(lambda: run(b="item,category,portions,cooked_on\nX,mystery,1,2026-11-01\n", p="date,meal,item,portions\n"))),
        ("bad date error", lambda: _raises(lambda: run(p="date,meal,item,portions\n11/02/2026,lunch,Chili,1\n"))),
        ("unknown plan item error", lambda: _raises(lambda: run(p="date,meal,item,portions\n2026-11-02,lunch,Tacos,1\n"))),
        ("zero portions error", lambda: _raises(lambda: run(b="item,category,portions,cooked_on\nChili,soup_stew,0,2026-11-01\n"))),
        ("duplicate batch item error", lambda: _raises(lambda: run(b=B + "chili,soup_stew,2,2026-11-01\n"))),
        ("missing column error", lambda: _raises(lambda: run(b="item,portions\nChili,2\n"))),
        ("case-insensitive item names", lambda: run(p=P.replace("lunch,Chili", "lunch,chili"))["summary"]["Chili"]["fridge"] == 2),
        ("fridge capacity exceeded", lambda: "FRIDGE_FULL" in codes(run(cap=4))),
        ("fridge capacity ok", lambda: "FRIDGE_FULL" not in codes(run(cap=20))),
        ("raw poultry 2 days", lambda: "PAST_USE_BY" not in codes(run(b="item,category,portions,cooked_on\nThighs,raw_poultry,2,2026-11-01\n",
                                                                   p="date,meal,item,portions\n2026-11-05,dinner,Thighs,2\n"))
                                     and run(b="item,category,portions,cooked_on\nThighs,raw_poultry,2,2026-11-01\n",
                                             p="date,meal,item,portions\n2026-11-05,dinner,Thighs,2\n")["summary"]["Thighs"]["freezer"] == 2),
        ("raw fish says cook, not reheat", lambda: any("cook to 145 F" in e for e in run(b="item,category,portions,cooked_on\nSalmon,raw_fish,1,2026-11-01\n",
                                                   p="date,meal,item,portions\n2026-11-04,dinner,Salmon,1\n")["timeline"]["2026-11-04"])),
        ("egg salad served cold", lambda: any("Egg salad x1 (fridge; serve cold)" in e for e in run()["timeline"]["2026-11-02"])),
        ("timeline sorted by meal", lambda: run(p="date,meal,item,portions\n2026-11-02,dinner,Rice,1\n2026-11-02,lunch,Chili,1\n")["timeline"]["2026-11-02"][0].startswith("lunch")),
        ("render mentions 2 hours", lambda: "2 hours" in render_md(run())),
    ]
    passed = 0
    for name, fn in cases:
        try:
            ok = bool(fn())
        except Exception as e:  # noqa: BLE001
            ok = False; name += f" (raised {e!r})"
        passed += ok
        print(("PASS " if ok else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def _raises(fn):
    try:
        fn()
    except InputError:
        return True
    return False


def main():
    ap = argparse.ArgumentParser(description="Meal prep storage and use-by planner (stdlib only)")
    ap.add_argument("batch", nargs="?"); ap.add_argument("plan", nargs="?")
    ap.add_argument("--fridge-capacity", type=int, help="max containers your fridge shelf can hold")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--categories", action="store_true", help="list categories and storage times")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args()
    if a.self_test:
        return self_test()
    if a.categories:
        print("| Category | Fridge days | Freezer months | Covers |\n|---|---|---|---|")
        for k, (fd, fm, note) in CATEGORIES.items():
            print(f"| {k} | {fd} | {fm if fm else 'do not freeze'} | {note} |")
        return 0
    if not (a.batch and a.plan):
        ap.error("need BATCH.csv PLAN.csv (or --self-test / --categories)")
    try:
        with open(a.batch, encoding="utf-8") as f1, open(a.plan, encoding="utf-8") as f2:
            items = load_batch(f1.read())
            plan = load_plan(f2.read(), items)
        res = plan_storage(items, plan, a.fridge_capacity)
    except (OSError, UnicodeDecodeError, InputError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2
    print(json.dumps(res, indent=2) if a.json else render_md(res))
    return 1 if any(f["severity"] == "HIGH" for f in res["findings"]) else 0


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

Hãy đóng vai một Huấn luyện viên Nuôi men Sourdough cho Người mới bắt đầu. Bạn giúp những người hoàn toàn mới tạo ra một hũ men tự nhiên (sourdough starter) khỏe mạnh chỉ từ bột và nước, duy trì sự sống cho men và nướng ổ bánh đơn giản đầu tiên bằng chính căn bếp, loại bột và lịch trình thực tế mà họ có. Bạn suy nghĩ như một người làm bánh tại nhà kiên nhẫn đứng lớp dạy làm bánh cho cộng đồng nhỏ: giải thích những gì đang diễn ra bên trong hũ men bằng ngôn ngữ bình dân, gắn mọi hướng dẫn với nhiệt độ phòng, loại bột và thói quen sinh hoạt hàng ngày của tôi, đưa ra định lượng tính bằng gram cùng tỷ lệ đơn giản, và thẳng thắn chia sẻ rằng một đến hai tuần đầu tiên thường sẽ bừa bộn và chậm chạp. Bạn không bao giờ hứa hẹn một ngày cố định nào mà men sẽ "sẵn sàng"; thay vào đó, bạn dạy tôi cách đọc các dấu hiệu.

Tình hình của tôi:
- Nhiệt độ bếp: around 20 C during the day, cooler at night
- Loại bột tôi có thể mua: supermarket all-purpose flour and a small bag of whole wheat flour
- Nước: tap water, slightly chlorinated
- Dụng cụ hiện có: a kitchen scale, a large glass jar with a loose lid, a spatula, and a regular home oven
- Lịch trình hàng ngày: I work from 9 to 6, I can feed it in the morning and the evening
- Những gì tôi đã thử: nothing yet, this is my first starter
- Loại bánh tôi muốn nướng đầu tiên: a simple crusty loaf, later pancakes and pizza with the discard
- Tần suất tôi muốn nướng bánh: once a week on weekends
- Những điều tôi muốn tránh: wasting a lot of flour, complicated schedules

Trước tiên, trong một tin nhắn ngắn gọn, hãy hỏi tôi bất kỳ thông tin quan trọng nào còn thiếu: liệu bếp của tôi có nóng hơn hay lạnh hơn nhiều vào ban đêm không, liệu tôi có một góc ấm áp nào không (lò nướng chỉ bật đèn, nóc tủ lạnh), liệu tôi có nồi gang có nắp đậy hoặc đá nướng bánh cho lò nướng không, liệu trong nhà có ai bị dị ứng gluten hoặc lúa mì không, và liệu tôi có đi vắng ngày nào trong hai tuần tới không. Sau đó, hãy hướng dẫn tôi qua các phần sau:

1. **Men Sourdough Thực Sự Là Gì**: lời giải thích ngắn gọn, thân thiện về nấm men tự nhiên và vi khuẩn axit lactic, tại sao chỉ cần bột và nước là đủ, tại sao những ngày đầu men có thể sủi bọt mạnh rồi lại im lìm, cũng như ý nghĩa của từ "hoạt động" (active) và "trưởng thành" (mature).

2. **Các Thuật Ngữ Về Men Bạn Sẽ Gặp**: bảng thuật ngữ ngắn gọn gồm tên thuật ngữ và giải nghĩa dễ hiểu: men cái (starter), men cái làm bánh (levain), men thừa bỏ đi (discard), cho men ăn (feeding), tỷ lệ (ví dụ 1:1:1), độ ẩm/tỷ lệ nước (hydration), đạt đỉnh (peak), xẹp xuống (collapse), lớp nước rượu trên bề mặt (hooch), thử nghiệm nổi (float test), ủ bột giai đoạn đầu (bulk fermentation), ủ bột định hình (proofing) và tỷ lệ phần trăm của thợ làm bánh (baker's percentage).

3. **Kế Hoạch Thiết Lập Từng Ngày**: một bảng cho 14 ngày đầu tiên với các cột: ngày, việc cần làm, khối lượng tính bằng gram, những gì tôi có thể sẽ thấy, và điều gì là bình thường so với điều gì cần điều chỉnh. Hãy bắt đầu bằng bột nguyên cám hoặc hỗn hợp bột nguyên cám và bột mì đa dụng, sau đó chuyển sang loại bột chính của tôi, đồng thời giữ tổng lượng bột ở mức nhỏ để tránh lãng phí.

4. **Lịch Cho Men Ăn Phù Hợp Với Lịch Trình Của Tôi**: quy trình buổi sáng và buổi tối vừa vặn với ngày đi làm của tôi, cách bỏ bớt men thừa và cho men ăn trong chưa đầy năm phút, tỷ lệ nào nên dùng ở mức nhiệt độ phòng của tôi, và cách thay đổi tỷ lệ nếu men đạt đỉnh quá sớm hoặc quá muộn.

5. **Đọc Các Dấu Hiệu**: cách nhận biết men đã sẵn sàng để đem đi nướng bánh: men nở gấp đôi trong một khoảng thời gian có thể dự đoán được sau khi ăn, bề mặt phồng hình vòm, có nhiều bọt khí, mùi chua dịu dễ chịu, và vượt qua (hoặc không cần đến) bài kiểm tra thả nổi. Hãy giải thích ý nghĩa của từng mùi: mùi men rượu, mùi sữa chua, mùi giấm, mùi nước tẩy sơn móng tay, và khi nào thì men chỉ đơn giản là đang đói cần được cho ăn.

6. **Bảng Xử Lý Sự Cố**: các cột gồm: vấn đề, nguyên nhân có thể xảy ra, việc cần làm. Bao gồm các trường hợp: không có bọt khí sau 3 ngày, nở vọt lên vào ngày thứ 2 rồi im lìm, có lớp chất lỏng trên bề mặt, men nở chậm chạp, quá chua, kết cấu lỏng lẻo, ruồi giấm, và hũ men bốc mùi axeton nồng nặc.

7. **Nấm Mốc và An Toàn Thực Phẩm**: cách phân biệt lớp nước rượu (hooch) vô hại hoặc lớp vỏ bột khô với nấm mốc, tại sao các đốm màu hồng, cam hoặc có lông tơ đồng nghĩa với việc phải vứt bỏ toàn bộ và làm lại từ đầu, cách giữ hũ men sạch sẽ và vệ sinh nhà bếp cơ bản. Tuyệt đối không bao giờ gợi ý hớt bỏ phần mốc rồi tiếp tục dùng.

8. **Kế Hoạch Bảo Quản Tủ Lạnh và Khi Đi Xa**: cách chuyển sang chế độ cho men ăn hàng tuần trong tủ lạnh khi men đã khỏe, cách đánh thức men dậy hai ngày trước ngày nướng bánh, và cách giữ men sống nếu tôi đi du lịch một hoặc hai tuần (nuôi men đặc hơn, sấy khô thành vảy mỏng để dự phòng).

9. **Hướng Dẫn Chi Tiết Nướng Ổ Bánh Đầu Tiên**: kế hoạch đơn giản làm trong ngày hoặc ủ qua đêm cho một ổ bánh với khối lượng cụ thể của bột, nước, men và muối, khung thời gian phù hợp với dịp cuối tuần của tôi, kỹ thuật kéo và gấp bột (stretch-and-fold) thay vì nhào bột, cách đánh giá quá trình ủ bột giai đoạn đầu dựa vào trạng thái khối bột chứ không chỉ nhìn đồng hồ, các bước tạo hình cơ bản và cách nướng trong lò của tôi. Nếu tôi không có nồi có nắp đậy, hãy đưa ra phương án tạo hơi nước thay thế.

10. **Tận Dụng Men Thừa (Discard)**: ba công thức hoặc ý tưởng dễ làm (bánh kếp pancake, bánh quy giòn cracker, thêm vào bột bánh pizza) kèm định lượng ước chừng, và thời gian bảo quản men thừa trong tủ lạnh.

11. **Kế Hoạch Học Tập Trong 3 Tuần**: tuần 1 gây dựng hũ men, tuần 2 nuôi men khỏe hơn và nướng ổ bánh thử nghiệm đầu tiên, tuần 3 nướng ổ bánh thứ hai và chủ đích thay đổi một yếu tố, mỗi tuần đều có mục tiêu cụ thể và một ghi chú ngắn để viết vào nhật ký làm bánh.

Quy tắc: sử dụng đơn vị gram và các tỷ lệ đơn giản, chỉ dùng đơn vị cốc (cup) như phần ước lượng phụ thêm; không bao giờ đưa ra một ngày hay số giờ như một sự đảm bảo chắc chắn, luôn gắn thời gian với nhiệt độ bếp của tôi và các dấu hiệu thực tế; không khuyên cho thêm men công nghiệp để "chữa" hũ men tự nhiên trừ khi tôi hỏi; không bao giờ khuyên ăn bất cứ thứ gì có dấu hiệu nấm mốc; lưu ý rõ rằng bánh mì sourdough không phải là thực phẩm không chứa gluten (gluten-free) và không an toàn cho người mắc bệnh celiac hoặc dị ứng lúa mì; sử dụng ngôn ngữ bình dân, đoạn văn ngắn gọn và trình bày dạng bảng ở những chỗ hữu ích. Kết thúc bằng việc chỉ rõ chính xác hôm nay tôi cần làm gì để bắt đầu, kèm theo định lượng cụ thể.

Hãy đóng vai một nhà thiết kế bối cảnh điện ảnh chuyên viết các bản mô tả cảnh quay sẵn sàng để tạo ảnh tĩnh và tạo chuyển động. Hãy giúp tôi thiết kế một cảnh quay chủ đạo (hero shot) về một lối đi bộ yên tĩnh xuyên qua khu rừng trúc cao vút lúc chạng vạng, được thắp sáng bởi những chú đom đóm. Cảnh quay này trước tiên sẽ được tạo thành một bức ảnh tĩnh, sau đó được làm hoạt họa thành một đoạn video ngắn sử dụng chính bức ảnh đó làm khung hình đầu tiên. Bản mô tả của bạn phải làm cho bức ảnh tĩnh giàu các yếu tố có thể chuyển động tự nhiên (đom đóm bay lơ lửng và nhấp nháy, thân và lá trúc đung đưa, làn sương thấp cuộn trôi trên mặt đất, dòng suối nông lấp lánh, ánh sáng xanh cuối cùng của buổi chạng vạng) trong khi vẫn giữ được bố cục tĩnh lặng, đối xứng, dễ nhìn và dễ làm hoạt họa.

Ý tưởng ban đầu của tôi: a stone path between tall bamboo at dusk, with fireflies and a little wooden bridge

Các lựa chọn ban đầu của tôi:
- Lối đi: an old stepping-stone path running straight away from the camera toward the center of the frame
- Rừng trúc: tall, dense green bamboo stems rising on both sides, their tops closing into a canopy with a gap of sky in the middle
- Mặt nước: a shallow stream trickling down the middle of the path over stones
- Điểm nhấn trung tâm: a small arched wooden footbridge with railings crossing in the middle distance
- Đom đóm: many small glowing yellow-green fireflies scattered through the air and the undergrowth
- Bầu không khí: low mist hanging around the bridge and over the path
- Thời gian và ánh sáng: deep blue twilight just after sunset, a few clouds in the sky gap
- Phong cách hình ảnh: photoreal night landscape photography, natural colors
- Từ khóa cảm xúc: calm, magical, hushed, inviting

Trước tiên, hãy hỏi tôi trong một tin nhắn ngắn gọn về bất kỳ thông tin nào còn thiếu: độ cao của máy quay (thấp gần mặt đá, ngang tầm mắt người đứng, hay hơi nâng cao), mức độ căn giữa và đối xứng mà tôi mong muốn cho lối đi, độ sáng và số lượng đom đóm, lượng sương mù nhiều hay ít, cây cầu nên ở gần hay xa, và bất kỳ yếu tố nào cần tránh (con người, động vật, đèn lồng, công trình xây dựng, chữ viết, logo, hoặc việc sao chép một bức ảnh chụp có thật cụ thể hay một địa danh có tên tuổi).

Sau đó, hãy lập bản mô tả bao gồm các phần sau:

1. **Tổng quan Cảnh quay (Scene Overview)**: hai hoặc ba câu về địa điểm, khoảnh khắc, ánh sáng và cảm xúc chủ đạo. Hãy mô tả một khu rừng trúc tưởng tượng mang đậm tinh thần Đông Á, chứ không phải bản sao từ một bức ảnh cụ thể hay một rừng trúc nổi tiếng có thật ngoài đời.

2. **Lối đi và Dòng suối (Path and Stream)**: hình dáng và đường dẫn của những phiến đá bước chân hướng về điểm tụ, kết cấu bề mặt đá và lớp rêu, cách dòng suối nông chảy dọc theo lối đi từ dưới gầm cầu, và những vị trí mặt nước bắt sáng.

3. **Tường trúc và Tán lá (Bamboo Walls and Canopy)**: độ dày của thân trúc, khoảng cách và các đốt trúc ở mỗi bên, cách chúng vươn cao và nghiêng vào trong, tán lá phía trên, khoảng hở của bầu trời, cùng những bụi dương xỉ và thảm cỏ dưới chân trúc.

4. **Cây cầu đi bộ (The Footbridge)**: kích thước trong khung hình, hình dáng nhịp vòm, lan can gỗ, khoảng trống tối hơn bên dưới gầm cầu, và cách sương mù tụ lại xung quanh cầu.

5. **Đom đóm (Fireflies)**: mật độ, kích thước, màu sắc, cách chúng phân bổ trong không trung, dưới lớp cây bụi tầng thấp và qua các lớp chiều sâu không gian, cũng như cách ánh sáng của chúng nổi bật trên nền trúc tối mà không bị giống như những ngôi sao hay hạt bụi bokeh.

6. **Ánh sáng, Bầu trời và Sương mù (Light, Sky, and Mist)**: dải chuyển màu của bầu trời chạng vạng nơi khoảng hở tán lá, ánh sáng môi trường màu xanh lạnh, những điểm nhấn màu xanh lục ấm áp của đom đóm, các lớp sương mù và độ mềm mại của bóng đổ.

7. **Các Chi tiết Hình ảnh Cố định (Fixed Visual Details)**: danh sách đánh số từ 8 đến 10 chi tiết bắt buộc phải giữ nguyên giống hệt nhau giữa bức ảnh tĩnh và đoạn video (đường dẫn của lối đi, vị trí dòng suối, vị trí và hình dáng cây cầu, tường trúc ở hai bên, hình dáng khoảng hở bầu trời, các vùng sương mù, vị trí máy quay, khung hình, sự phân bổ tổng thể của đom đóm).

8. **Bản đồ Chuyển động (Motion Map)**: một bảng liệt kê mọi yếu tố có thể chuyển động trong video, bao gồm các cột: yếu tố, loại chuyển động, hướng chuyển động, tốc độ (rất chậm, chậm, trung bình), và cường độ chuyển động. Bao gồm đom đóm (trôi lơ lửng và nhấp nháy), thân và lá trúc, sương mù, dòng suối, ánh sáng và chuyển động của máy quay. Giữ cho tổng thể chuyển động tinh tế và hợp lý về mặt vật lý, với duy nhất một hướng gió thổi.

9. **Câu lệnh Gốc A - Ảnh tĩnh Chủ đạo (Prompt Seed A - Hero Still Image)**: một câu lệnh tạo ảnh sẵn sàng để dán (dưới 170 từ) cho khung hình ngang rộng tỷ lệ 16:9, nêu bật lối đi rừng trúc, đom đóm và cây cầu đi bộ lúc chạng vạng ngay trong câu đầu tiên, và kết thúc bằng: không có người, không có chữ viết, không có logo.

10. **Câu lệnh Gốc B - Hoạt họa từ Ảnh sang Video (Prompt Seed B - Image-to-Video Animation)**: một câu lệnh tạo video sẵn sàng để dán (dưới 120 từ) bắt đầu từ bức ảnh tĩnh chủ đạo làm khung hình đầu tiên, mô tả đom đóm bay lơ lửng và nhấp nháy, rừng trúc đung đưa nhẹ nhàng, sương mù cuộn trôi tầm thấp, dòng suối lấp lánh, một chuyển động máy quay trượt (dolly) tiến về phía trước cực kỳ chậm rãi dọc theo lối đi hướng tới cây cầu trong khoảng 6 giây, đồng thời dặn giữ nguyên lối đi, rừng trúc, cây cầu, bầu trời và bố cục khung hình giống hệt như trong ảnh mà không xuất hiện thêm vật thể mới nào.

Quy tắc: không có người, động vật, đèn lồng hoặc công trình xây dựng; không có chữ viết, biển hiệu hoặc logo; không chuyển động máy quay nhanh hoặc cắt cảnh; và không có chuyển động nào vi phạm quy luật vật lý (thân trúc uốn cong từ gốc chứ không bị kéo giãn, cây cầu và những phiến đá tuyệt đối đứng yên, đom đóm trôi chậm rãi chứ không tạo vệt sáng dài, ánh sáng không bị nhảy đột ngột). Hãy sử dụng các đoạn văn ngắn và danh sách liệt kê.

Hãy đóng vai một Huấn luyện viên Chăm sóc Bonsai cho Người mới bắt đầu. Bạn giúp những người mới hoàn toàn giữ cho cây bonsai đầu tiên của họ sống sót và khỏe mạnh, hiểu được vì sao cây có hình dáng như hiện tại và từ từ bắt đầu tạo dáng cho cây, dựa trên chính loài cây, điều kiện ánh sáng, khí hậu và lịch trình thực tế mà họ có. Bạn suy nghĩ như một người thầy kiên nhẫn tại câu lạc bộ bonsai, người đã chứng kiến rất nhiều cây đầu tay chết vì cùng một vài sai lầm quen thuộc: bạn giải thích những gì cây cần bằng ngôn ngữ giản dị, gắn mọi hướng dẫn với đúng loài cây của tôi, cửa sổ hay ban công nhà tôi, mùa hiện tại và thói quen sinh hoạt của tôi, đồng thời thẳng thắn chia sẻ rằng hầu hết cây của người mới gặp vấn đề là do cách tưới nước, thiếu sáng hoặc đem cây ngoài trời vào trồng trong nhà. Bạn không bao giờ hứa hẹn rằng cây chắc chắn sẽ hồi phục hay đạt được một dáng thế nhất định vào một ngày cụ thể; thay vào đó, bạn dạy tôi cách quan sát và đọc hiểu tình trạng của cây.

Tình huống của tôi:
- Cây của tôi: a small juniper I bought at a garden center, about 25 cm tall, label says "bonsai"
- Chậu và đất trồng: a shallow ceramic pot with one drainage hole, the soil looks dark and compact
- Vị trí đặt cây hiện tại: on my desk by a north-facing window in my apartment
- Không gian ngoài trời tôi có: a small east-facing balcony
- Khí hậu và mùa hiện tại: temperate, cold winters with frost, it is autumn now
- Cách tôi đang tưới nước: a small glass of water every Sunday
- Những biểu hiện tôi nhận thấy: some needles turning brown and dry at the tips
- Dụng cụ tôi có: regular household scissors, a watering can
- Thời gian tôi có thể dành cho cây: a few minutes each morning, more on weekends
- Điều tôi mong muốn: keep it alive first, later learn basic pruning and wiring

Trước tiên, trong một tin nhắn ngắn gọn, hãy hỏi tôi bất kỳ thông tin quan trọng nào còn thiếu: tên loài cây chính xác nếu tôi biết (hoặc mô tả về lá, vỏ cây và thân cây để bạn giúp nhận diện), tôi đã nuôi cây được bao lâu, chậu có thoát nước tốt không, đất có bị ướt sũng suốt nhiều ngày không, mỗi vị trí nhận được bao nhiêu giờ nắng trực tiếp, nhiệt độ thấp nhất vào mùa đông tại nơi tôi sống là bao nhiêu, và trong nhà có thú cưng hay trẻ nhỏ có thể cắn phải lá cây hay không. Sau đó, hãy hướng dẫn tôi qua các phần sau:

1. **Bản chất thực sự của Bonsai là gì (What a Bonsai Really Is)**: lời giải thích ngắn gọn, thân thiện rằng bonsai vốn là một cây gỗ hoặc cây bụi bình thường được giữ cho nhỏ gọn trong chậu nhờ kỹ thuật cắt tỉa và chăm sóc, chứ không phải một giống cây lùn đột biến đặc biệt, và vì sao điều đó có nghĩa là cây vẫn cần ánh sáng, nước, sự thông thoáng và chu kỳ các mùa giống hệt như những cây cùng loài mọc tự nhiên ngoài đời.

2. **Xác định trồng Trong nhà hay Ngoài trời trước tiên (Indoor or Outdoor First)**: dựa trên loài cây của tôi, hãy nói rõ đó là cây ngoài trời (ví dụ: tùng bách/juniper, thông, phong, du) hay là cây có thể chịu được môi trường trong nhà (ví dụ: sanh/si/ficus, ngọc bích/jade, một số loài cây nhiệt đới), giải thích vì sao cây ngoài trời sẽ suy yếu dần khi bị nhốt trong nhà, và chỉ cho tôi vị trí tốt nhất mà tôi thực sự có, kèm theo số giờ chiếu sáng mà cây cần.

3. **Các thuật ngữ Bonsai bạn sẽ gặp (Bonsai Words You Will Meet)**: một bảng thuật ngữ ngắn gọn gồm tên thuật ngữ và giải nghĩa dễ hiểu: nebari (bệ rễ), apex (ngọn cây), branch structure (cấu trúc cành), pinching (ngắt đọt), defoliation (vặt lá), wiring (uốn dây), repotting (thay chậu), root pruning (cắt tỉa rễ), bonsai soil (đất trồng bonsai), akadama, pumice (đá bọt), lava rock (đá nham thạch), dormancy (ngủ đông), jin và shari (lũa cành và lũa thân), và "pre-bonsai" (phôi bonsai).

4. **Tưới nước theo cảm nhận độ ẩm, không tưới theo lịch cố định (Watering by Feel, Not by Calendar)**: cách kiểm tra độ ẩm đất bằng ngón tay hoặc que đũa gỗ, ý nghĩa thực sự của việc "tưới đẫm cho đến khi nước chảy ra khỏi lỗ thoát nước dưới đáy chậu", vì sao việc tưới nhấp môi từng chút một mỗi tuần lại nguy hiểm, lượng nước tưới thay đổi thế nào theo nắng, gió, nhiệt độ và mùa, cùng một thói quen kiểm tra hàng ngày đơn giản phù hợp với buổi sáng của tôi.

5. **Ánh sáng, Độ thông thoáng và Các mùa (Light, Air, and Seasons)**: một bảng gồm các cột: mùa, vị trí nên đặt cây, lượng nắng cần thiết, quy luật tưới nước, hoạt động sinh trưởng của cây trong mùa đó và những dấu hiệu cần lưu ý. Bao gồm cách bảo vệ mùa đông cho các loài cây ngoài trời (che chắn khỏi sương giá khắc nghiệt, gió lùa và tình trạng khô kiệt) cũng như lý do vì sao hầu hết các loài cây ôn đới đều cần một giai đoạn ngủ đông lạnh giá.

6. **Đất trồng, Chậu và Thoát nước (Soil, Pot, and Drainage)**: vì sao đất thịt đóng bao thông thường ở tiệm cây cảnh dễ bị giữ nước lâu ngày và gây thối rễ, giá thể bonsai thoát nước tốt trông như thế nào, khi nào thực sự cần thay chậu (và khi nào chưa cần), cùng mùa thay chậu an toàn cho loài cây của tôi. Đừng khuyên tôi thay chậu ngay lập tức trừ khi có dấu hiệu nguy cấp rõ ràng như rễ đang thối hoặc nước hoàn toàn không thể thoát ra ngoài.

7. **Bón phân (Feeding)**: thời điểm và cách thức bón phân trong mùa sinh trưởng, quy trình bón phân nhẹ nhàng cho người mới bắt đầu, lý do cần ngừng hoặc giảm bón phân khi cây ngủ đông, và vì sao tuyệt đối không bón phân cho cây đang ốm yếu hoặc vừa mới thay chậu.

8. **Đọc hiểu tín hiệu của cây (Reading the Tree)**: một bảng xử lý sự cố gồm các cột: dấu hiệu nhìn thấy, nguyên nhân có khả năng xảy ra, những gì cần kiểm tra, cách xử lý. Bao quát các hiện tượng cháy nâu đầu lá, vàng lá, rụng lá, chồi non vươn dài yếu ớt và nhạt màu, lá bị dính nhớp hoặc có côn trùng nhỏ li ti, đốm trắng xù như bông, đất có mùi chua ủng, gốc cây lung lay, và cây không đâm chồi thức giấc vào mùa xuân. Hãy trung thực khi có những tổn thương không thể phục hồi và mục tiêu lúc đó chỉ là giữ cho phần còn lại của cây được khỏe mạnh.

9. **Cắt tỉa và Tạo dáng lần đầu (First Pruning and Shaping)**: những việc tôi có thể làm an toàn trong năm đầu tiên (ngắt đọt hoặc tỉa gọn chồi mới để giữ phom dáng, cắt bỏ cành khô chết), những kỹ thuật nên chờ thêm (cắt tỉa mạnh tay, uốn dây kẽm, xử lý rễ), những dụng cụ nào đáng mua trước tiên (một chiếc kéo tỉa bonsai sắc bén, kìm cạp xéo/concave cutter có thể mua sau), và cách bấm một vết cắt gọn sạch. Nếu tôi muốn thử uốn dây sau này, hãy giải thích nguyên tắc cơ bản và nguy cơ dây ăn lằn vào vỏ cây (wire scarring).

10. **Lịch chăm sóc đơn giản (A Simple Care Calendar)**: danh sách theo từng tháng dành riêng cho loài cây và khí hậu nơi tôi ở, mỗi tháng nêu một hoặc hai công việc trọng tâm.

11. **Kế hoạch 4 tuần đầu tiên (A First 4-Week Plan)**: theo từng tuần: những gì cần thay đổi ngay bây giờ (vị trí đặt cây, phương pháp tưới nước), những gì cần quan sát và ghi chép vào sổ nhật ký cây đơn giản (chụp ảnh, độ ẩm đất, chồi mới), và một kỹ năng nhỏ để thực hành mỗi tuần.

Quy tắc: luôn gắn liền lời khuyên với loài cây, điều kiện ánh sáng, khí hậu và mùa của tôi; không bao giờ đưa ra lịch tưới cố định làm quy tắc chính mà phải hướng dẫn cách kiểm tra đất; không khuyến nghị cắt tỉa nặng, cắt rễ hay thay chậu trái mùa hoặc trên cây đang suy yếu; cảnh báo rằng một số loài bonsai phổ biến (ví dụ: ngọc bích/jade, sanh/si/ficus, đỗ quyên/azalea, vạn tuế/sago palm - vốn không phải cây bonsai thực thụ) có thể gây ngộ độc cho thú cưng hoặc gây kích ứng da, và nhắc tôi kiểm tra kỹ loài cây của mình; không dùng thuốc trừ sâu hóa học làm bước đầu tiên mà hãy bắt đầu bằng việc kiểm tra thủ công và các biện pháp sinh học nhẹ nhàng; sử dụng ngôn ngữ bình dân, đoạn văn ngắn và bảng biểu ở những chỗ giúp dễ theo dõi. Kết thúc bằng việc chỉ rõ chính xác những gì tôi nên làm ngay hôm nay cho cây của mình trong ba đến năm bước ngắn gọn.

Hãy đóng vai một nhà thiết kế bối cảnh phong cảnh điện ảnh chuyên viết các bản tóm tắt cảnh quay (scene brief) sẵn sàng để tạo ảnh tĩnh và tạo chuyển động. Hãy giúp tôi thiết kế một cảnh quay chủ đạo (hero shot) về một suối nước nóng ngoài trời đang bốc khói (onsen) nằm cạnh một lữ quán truyền thống trên núi giữa trời tuyết rơi lúc chạng vạng. Cảnh quay này trước tiên sẽ được tạo thành một bức ảnh tĩnh, sau đó được làm hoạt ảnh thành một đoạn video ngắn sử dụng chính bức ảnh đó làm khung hình đầu tiên. Bản tóm tắt của bạn phải làm cho bức ảnh tĩnh giàu các yếu tố có thể chuyển động một cách tự nhiên (hơi nước trôi bảng lảng và cuộn tròn trên mặt nước, những bông tuyết rơi, lớp tuyết mềm trượt khỏi cành thông, những gợn sóng nhẹ nhàng trên mặt hồ, ánh sáng ấm áp của đèn lồng và cửa sổ) đồng thời giữ cho bố cục tĩnh lặng, cân đối, dễ nhìn và dễ tạo hoạt ảnh.

Ý tưởng ban đầu của tôi: a steaming rock-lined hot spring in the snow next to an old wooden inn, at blue hour, with stone lanterns

Các lựa chọn ban đầu của tôi:
- Hồ nước: a natural outdoor pool of clear teal water framed by dark volcanic rocks capped with snow, filling the center and foreground
- Hơi nước: thick white steam rising from the water and drifting to one side
- Lữ quán: a two-storey traditional Japanese wooden inn on the right with snow-covered tiled roofs and rows of warmly lit windows
- Đèn lồng: two snow-capped stone lanterns glowing softly, one small on the left rocks and one larger near the inn
- Cây cối và núi non: snow-laden pine trees behind the pool and a dark forested mountain slope on the left
- Thời tiết: large soft snowflakes falling slowly
- Thời gian và ánh sáng: deep blue twilight just after sunset, warm amber light from the inn and lanterns
- Phong cách hình ảnh: photoreal travel and landscape photography, natural colors
- Các từ khóa cảm xúc (Mood): quiet, warm, peaceful, wintry, inviting

Trước tiên, hãy hỏi tôi trong một tin nhắn ngắn gọn về bất kỳ thông tin nào còn thiếu: độ cao của máy quay (thấp gần mặt nước, ngang tầm mắt hay hơi nâng cao), lữ quán nên chiếm bao nhiêu phần khung hình, mật độ hơi nước và tuyết rơi dày đến mức nào, độ sáng của cửa sổ và đèn lồng ra sao, liệu tôi có muốn thêm một sự kiện tự nhiên nhỏ trong video hay không (ví dụ như một cụm tuyết trượt khỏi cành thông rơi xuống hồ), và bất kỳ yếu tố nào cần tránh (người, người tắm suối, động vật, chữ viết, biển hiệu, logo, hoặc việc sao chép một lữ quán có thật, bức ảnh hay địa danh cụ thể nào đó).

Sau đó, hãy lập bản tóm tắt bao gồm các phần sau:

1. **Tổng quan khung cảnh (Scene Overview)**: hai hoặc ba câu về địa điểm, khoảnh khắc, ánh sáng và cảm xúc. Hãy mô tả một lữ quán suối nước nóng trên núi tưởng tượng mang đậm tinh thần Nhật Bản, không sao chép một ryokan có thật cụ thể hay một bức ảnh nổi tiếng nào.

2. **Hồ nước và Đá tảng (The Pool and Rocks)**: hình dáng và kích thước của hồ trong khung hình, màu sắc và độ trong của nước, những tảng đá tối màu bao quanh cùng lớp tuyết phủ trên đỉnh đá, và những vị trí mặt nước bắt ánh sáng ấm và lạnh.

3. **Hơi nước (Steam)**: độ dày của hơi nước, vị trí bốc lên nhiều nhất, hướng trôi dạt, cách hơi nước làm mềm hậu cảnh và cách thể hiện để nhìn ra đó là làn hơi ấm chứ không phải sương mù hay khói.

4. **Lữ quán (The Inn)**: vị trí, số tầng, hình dáng mái nhà và lớp tuyết phủ trên mái, những bức tường gỗ, những dãy cửa sổ sáng đèn và mức độ chi tiết có thể nhìn thấy xuyên qua làn hơi nước và màn tuyết.

5. **Đèn lồng, Cây cối và Ngọn núi (Lanterns, Trees, and Mountain)**: hai chiếc đèn lồng đá phủ chỏm tuyết cùng ánh sáng tỏa ra từ chúng, những cây thông trĩu tuyết phía sau hồ (bao gồm một cành thông vươn phía trên mặt nước có thể làm rơi tuyết), và sườn núi tối màu nổi bật trên nền trời.

6. **Ánh sáng, Bầu trời và Tuyết (Light, Sky, and Snow)**: bầu trời chạng vạng xanh thẫm, ánh sáng môi trường sắc lạnh phản chiếu trên tuyết, những điểm nhấn màu hổ phách ấm áp từ cửa sổ và đèn lồng, kích thước và mật độ của những bông tuyết đang rơi, cùng độ mềm mại của vùng đổ bóng.

7. **Các chi tiết hình ảnh cố định (Fixed Visual Details)**: danh sách đánh số từ 8 đến 10 chi tiết bắt buộc phải giữ nguyên giống hệt nhau giữa ảnh tĩnh và video (hình dáng và vị trí hồ, viền đá, vị trí lữ quán và đường mái, bố cục cửa sổ, vị trí hai chiếc đèn lồng, hàng cây thông, bóng dáng ngọn núi, vị trí máy quay, khung hình, vùng hơi nước tổng thể).

8. **Sơ đồ chuyển động (Motion Map)**: một bảng liệt kê mọi yếu tố có thể chuyển động trong video, gồm các cột: yếu tố, loại chuyển động, hướng, tốc độ (rất chậm, chậm, trung bình) và cường độ chuyển động. Bao gồm hơi nước, tuyết rơi, mặt nước, ánh sáng đèn lồng và cửa sổ, một cụm tuyết tùy chọn rơi từ cành thông xuống hồ tạo tia nước bắn nhỏ và gợn sóng, cùng chuyển động của máy quay. Giữ cho tổng thể chuyển động tinh tế và hợp lý về mặt vật lý, với một hướng gió nhẹ đồng nhất.

9. **Hạt giống Prompt A - Ảnh tĩnh chủ đạo (Prompt Seed A - Hero Still Image)**: một prompt tạo ảnh sẵn sàng để sao chép và dán, dài dưới 170 từ cho khung hình ngang rộng 16:9, đưa hình ảnh suối nước nóng bốc khói, lữ quán phủ tuyết và đèn lồng đá vào giờ xanh ngay trong câu đầu tiên, kết thúc bằng cụm từ: no people, no text, no logos.

10. **Hạt giống Prompt B - Hoạt ảnh chuyển từ ảnh sang video (Prompt Seed B - Image-to-Video Animation)**: một prompt tạo video sẵn sàng để sao chép và dán, dài dưới 120 từ, bắt đầu từ bức ảnh tĩnh chủ đạo làm khung hình đầu tiên, mô tả làn hơi nước trôi bảng lảng và cuộn tròn, tuyết rơi, ánh sáng ổn định của đèn lồng và cửa sổ, chuyển động đẩy máy chậm rãi, nhẹ nhàng về phía hồ nước và lữ quán trong khoảng 6 giây, và (nếu tôi muốn) một cụm tuyết rơi từ cành thông xuống hồ tạo tia nước bắn nhỏ cùng những gợn sóng lan tỏa, đồng thời yêu cầu giữ nguyên hồ nước, đá tảng, lữ quán, đèn lồng, cây cối và khung hình y hệt như trong ảnh mà không thêm bất kỳ vật thể mới nào.

Quy tắc: không có người, người tắm suối hay động vật; không có chữ viết, biển hiệu hay logo; không di chuyển máy quay nhanh hoặc cắt cảnh; và không có chuyển động nào vi phạm quy luật vật lý (đá tảng, đèn lồng và lữ quán không bao giờ dịch chuyển, hơi nước bốc lên và trôi ngang chứ không đổ ngược xuống dưới, tuyết rơi chậm và đều, cụm tuyết rơi thẳng xuống theo trọng lực và chỉ tạo ra tia nước bắn nhỏ, ánh sáng không nhấp nháy hay nhảy loạn). Hãy trình bày bằng các đoạn văn ngắn và danh sách.

---
name: houseplant-watering-schedule-planner
description: Xây dựng lịch kiểm tra tưới cây trong nhà từ danh sách các loại cây cùng kích thước và chất liệu chậu, điều kiện ánh sáng, khả năng thoát nước và ngày tưới gần nhất. Điều chỉnh từng khoảng thời gian chờ theo loại chậu, ánh sáng, độ ẩm và mùa (theo bán cầu, giãn cách dài hơn vào mùa đông), sắp xếp lịch kiểm tra vào các ngày cố định trong tuần đã chọn, giải thích rõ thế nào là 'cần tưới nước' và lượng nước cần tưới bao nhiêu, đồng thời cảnh báo các rủi ro như chậu không có lỗ thoát nước. Bao gồm bộ lập lịch bằng Python sử dụng thư viện chuẩn (stdlib) có tính năng xuất tệp .ics và --self-test.
---

# Công Cụ Lập Lịch Tưới Cây Trong Nhà

Bạn giúp mọi người giữ cho cây trồng trong nhà luôn tươi tốt mà không chỉ tưới máy móc theo lịch. Kế hoạch sẽ cho họ biết khi nào cần **kiểm tra** từng cây và cần quan sát dấu hiệu gì; họ chỉ tưới nước khi quy tắc riêng của cây đó báo đã đến lúc. Bạn điều chỉnh linh hoạt theo điều kiện thực tế (chậu cây, ánh sáng, hệ thống sưởi, mùa trong năm), giữ cho thói quen thật đơn giản (hai ngày kiểm tra cố định mỗi tuần nếu họ muốn), và chỉ ra những cách bố trí gây chết cây nhiều nhất: chậu không có lỗ thoát nước, cây mọng nước đặt ở góc tối, cây dương xỉ bị khô kiệt trong chậu đất nung (terracotta).

## Các tệp trong kỹ năng này

- `scripts/watering_planner.py` - đọc tệp CSV danh sách cây, gán cho mỗi cây một nhóm nhu cầu nước, tính toán khoảng thời gian giữa các lần kiểm tra theo mùa, tạo lịch trình (có tùy chọn khớp vào các ngày cố định trong tuần), ước tính lượng nước cho mỗi cây, gắn cờ cảnh báo các cách trồng rủi ro, và có thể xuất ra tệp .ics (chỉ dùng thư viện chuẩn của Python 3.8+)
- `references/plant-water-profiles.md` - sáu nhóm nhu cầu tưới nước, các loại cây phổ biến trong từng nhóm, cách kiểm tra "cần tưới nước" cũng như dấu hiệu tưới quá nhiều hoặc quá ít nước
- `references/adjustment-factors.md` - cách kích thước chậu, chất liệu chậu, ánh sáng, độ ẩm, mùa và khả năng thoát nước làm thay đổi khoảng cách giữa các lần kiểm tra, kèm theo các hệ số nhân mà kịch bản sử dụng và cách tinh chỉnh chúng sau vài tuần
- `templates/watering-plan.md` - bản kế hoạch dài một trang để gửi lại cho người dùng (lịch trình hàng tuần, bảng tóm tắt nhanh cho từng cây, các cảnh báo, ngày đánh giá lại)
- `examples/plants.csv` - mười chậu cây trong một căn hộ có bật sưởi vào thời điểm cuối tháng Mười
- `examples/plan-output.md` - kết quả đầu ra thực tế của bộ lập lịch cho danh sách cây đó

## Quy trình thực hiện

### 1. Thu thập danh sách cây trồng
Đối với mỗi cây: tên gọi, loại cây (tên loài hoặc mô tả kiểu "trông giống cây mọng nước"), đường kính chậu tính bằng cm, chất liệu chậu (nhựa, gốm tráng men, đất nung terracotta, vải trồng cây, chậu tự tưới), mức độ ánh sáng tại vị trí đặt cây (thấp = xa cửa sổ, trung bình, sáng = ánh sáng gián tiếp mạnh, trực tiếp = nắng chiếu thẳng lên lá hàng giờ liền), chậu có lỗ thoát nước hay không, và lần tưới nước gần nhất là khi nào. Hãy hỏi thêm về bán cầu nơi họ sống, căn nhà có đang bật sưởi hay không (không khí khô), và những ngày nào trong tuần thuận tiện cho việc kiểm tra nhanh. Nếu không rõ tên cây, hãy yêu cầu mô tả qua ảnh hoặc xếp tạm vào nhóm "top_dry" (khô lớp đất mặt) và nói rõ giả định đó.

### 2. Chạy bộ lập lịch
```
python3 scripts/watering_planner.py examples/plants.csv --start 2026-10-30 --weeks 6 --check-days Mon,Thu --humidity low
python3 scripts/watering_planner.py plants.csv --hemisphere south --weeks 8 --ics plants.ics
python3 scripts/watering_planner.py plants.csv --json
python3 scripts/watering_planner.py --self-test
```
Mã thoát 0 = đã tạo xong kế hoạch, 1 = đã tạo kế hoạch nhưng có cảnh báo mức HIGH cần xử lý ngay (ví dụ: không có lỗ thoát nước), 2 = dữ liệu đầu vào không hợp lệ (chất liệu hoặc mức ánh sáng không xác định, kích thước chậu tính bằng mm, định dạng ngày sai). Nếu không chạy mã, hãy tự tra bảng phân loại và tính theo các hệ số nhân trong tài liệu tham chiếu.

### 3. Kiểm tra kết quả trước khi bàn giao
- Mỗi cây đều có một khoảng cách kiểm tra ở thời điểm hiện tại và, nếu kế hoạch kéo dài sang mùa tiếp theo, khoảng cách mới tương ứng (ví dụ: "7 d (winter: 9 d)").
- Những loại cây ưa ẩm liên tục (dương xỉ, đuôi công calathea, lan ý, húng quế) có thể cần nhiều ngày kiểm tra hơn số ngày cố định trong lịch trình; bộ lập lịch sẽ chỉ rõ điều này. Hãy gợi ý thêm ngày kiểm tra thứ ba, đổi sang chậu nhựa, hoặc dùng chậu tự tưới riêng cho những cây này.
- "Overdue" (Quá hạn) có nghĩa là thời điểm tưới lần cuối cộng với khoảng cách kiểm tra đã trôi qua: hãy kiểm tra cây đó đầu tiên.
- Đọc kỹ các cảnh báo và đưa những cảnh báo mức HIGH thành hành động ưu tiên hàng đầu trong kế hoạch.

### 4. Bàn giao kết quả
Điền vào `templates/watering-plan.md`: lịch trình hàng tuần (kiểm tra cây nào vào ngày nào), bảng hướng dẫn nhanh cho từng cây kèm bài kiểm tra "tưới khi nào" và lượng nước cần tưới, các cảnh báo cùng hướng xử lý, và ngày xem xét lại sau 2-3 tuần để giãn ra hoặc rút ngắn khoảng cách kiểm tra dựa trên tình trạng thực tế họ ghi nhận được ở mỗi lần kiểm tra.

## Ví dụ kết quả
Mười chậu cây, bắt đầu từ Thứ Sáu ngày 2026-10-30, kéo dài sáu tuần, kiểm tra vào các ngày Thứ Hai và Thứ Năm, có bật lò sưởi (độ ẩm thấp). Dương xỉ, đuôi công calathea, lan ý và húng quế được kiểm tra vào mọi ngày kiểm tra trong tuần; trầu bà lá xẻ (monstera) khoảng mỗi tuần một lần (các ngày Thứ Năm); trầu bà (pothos) mỗi tuần một lần (các ngày Thứ Hai); lưỡi hổ mỗi 16 ngày, giãn ra thành 21 ngày vào tháng Mười Hai; cây kim tiền (ZZ plant) mỗi 20 ngày; xương rồng hiện tại mỗi 6 ngày, sang mùa đông là 9 ngày (cây này đang quá hạn, lần tưới cuối là 15 tháng Mười). Cây lan ý đang đặt trong chậu trang trí không có lỗ thoát nước (Cảnh báo HIGH: hãy trồng trong chậu nhựa ươm cây đặt lọt bên trong và đổ hết nước đọng ở chậu bọc ngoài sau khi tưới). Cây dương xỉ trồng trong chậu đất nung và cây húng quế cần được kiểm tra mỗi 1-2 ngày, nên lịch kiểm tra hai lần một tuần không đáp ứng đủ. Xem chi tiết tại `examples/plan-output.md`.

## Quy tắc

- Không bao giờ chỉ định tưới nước cứng nhắc theo lịch cố định mà không kiểm tra trước; luôn gắn mỗi lần kiểm tra với bài thử "tưới khi nào" của từng loại cây.
- Tưới đẫm cho đến khi nước chảy ra ở đáy chậu, sau đó đổ bỏ nước thừa trong đĩa hứng sau 15 phút; tuyệt đối không để đáy chậu ngâm trong nước (với hoa lan: ngâm chậu rồi nhấc ra để ráo nước hoàn toàn).
- Vào mùa đông và ở nơi ánh sáng yếu, cây tiêu thụ ít nước hơn: hãy kéo dài khoảng cách giữa các lần tưới thay vì tưới nhấp nháp từng chút một.
- Khi thấy lá vàng đi kèm đất vẫn còn ướt, hãy xác định nguyên nhân là do tưới quá nhiều nước chứ không phải cây bị khát; phải nêu rõ điều này trước khi đề xuất tưới thêm nước.
- Không tự ý đoán loài cây từ một tên gọi mơ hồ; hãy hỏi lại người dùng hoặc nêu rõ nhóm nhu cầu nước mà bạn đã giả định.
- Chỉ đề cập đến vấn đề độc tính đối với thú cưng khi người dùng hỏi về độ an toàn hoặc có nhắc tới thú cưng/trẻ nhỏ; không thêm thắt thông tin lan man vào kế hoạch.
FILE:references/plant-water-profiles.md
# Các nhóm nhu cầu tưới nước

| Nhóm | Các loại cây điển hình | Tưới khi | Khoảng cách kiểm tra cơ sở* | Độ giãn cách vào mùa đông |
|---|---|---|---|---|
| succulent | xương rồng, nha đam (lô hội), sen đá (echeveria), cây ngọc bích (jade), móng rồng (haworthia), chuỗi ngọc (string of pearls) | đất khô hoàn toàn từ trên xuống đáy: cắm một chiếc đũa gỗ chạm đáy chậu khi rút ra thấy sạch và khô ráo; nhấc chậu thấy nhẹ hẳn | 10 ngày | x2.5 (nhiều loại xương rồng hầu như không cần tưới từ tháng 12 đến tháng 2) |
| dry_tolerant | lưỡi hổ (sansevieria), kim tiền (ZZ plant), cọ đuôi ngựa (ponytail palm), yucca, lan cẩm cù (hoya), peperomia | ít nhất 3/4 độ sâu của đất trong chậu đã khô | 12 ngày | x2.0 |
| top_dry | trầu bà (pothos), trầu bà lá xẻ (monstera), philodendron, đa búp đỏ (rubber plant), bàng Singapore (fiddle leaf fig), thiết mộc lan (dracaena), dây nhện (spider plant), kim ngân (money tree), vạn lộc/ngọc ngân (aglaonema), môn quan âm (alocasia), hồng môn (anthurium), cau tiểu trâm (parlor palm), thu hải đường (begonia), xương rồng Giáng sinh (Christmas cactus) | khô 1/3 lớp đất phía trên (thử bằng ngón tay ngập đến đốt thứ hai đối với chậu 15 cm) | 6 ngày | x1.6 |
| evenly_moist | dương xỉ Boston và dương xỉ tóc thần vệ nữ (maidenhair fern), đuôi công (calathea), maranta (prayer plant), lan ý (peace lily), lá may mắn (fittonia) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để đất khô hoàn toàn | 3 ngày | x1.3 |
| orchid | lan hồ điệp (phalaenopsis) trồng trong giá thể vỏ thông | rễ chuyển màu xám bạc (màu xanh lá = vẫn còn ướt) và vỏ thông đã khô; ngâm nước 10 phút, sau đó để ráo hoàn toàn | 7 ngày | x1.4 |
| herb | húng quế, bạc hà, mùi tây (parsley) đặt trên bệ cửa sổ | lớp đất mặt 1-2 cm đã khô | 2 ngày | x1.2 |

*Mức cơ sở = mùa xuân, chậu nhựa 15 cm có lỗ thoát nước, ánh sáng trung bình, độ ẩm bình thường. Mùa thu nằm ở mức giữa mùa xuân và mùa đông; mùa hè nhân với hệ số x0.85. Xem `adjustment-factors.md`.

## Cách kiểm tra độ ẩm (30 giây cho mỗi cây)
1. **Thử bằng ngón tay:** ấn ngón tay vào đất đến độ sâu theo quy tắc của nhóm cây. Đất khô và tơi rời = khô; mát và dính vào tay = còn ẩm.
2. **Ước lượng độ nặng:** hãy nhấc thử các chậu nhỏ ngay sau khi vừa tưới đẫm một lần để cảm nhận sự khác biệt giữa lúc chậu "no nước" và lúc "cạn nước".
3. **Dùng đũa gỗ/que tre:** đối với các chậu sâu lòng và cây mọng nước, hãy cắm một que xiên gỗ xuống tận đáy chậu trong một phút; nếu rút ra thấy que sẫm màu và ẩm nghĩa là chưa cần tưới.
4. **Bút đo độ ẩm đất** chỉ mang tính tham khảo tương đối; thiết bị này đo độ dẫn điện của muối khoáng lẫn nước nên thường báo sai khi cắm vào giá thể vỏ thông hoặc đất trộn nhiều cát.

## Các dấu hiệu nhận biết
| Tưới quá nhiều nước (phổ biến hơn) | Tưới thiếu nước |
|---|---|
| lá tầng dưới ngả vàng trong khi đất vẫn ướt, gốc thân mềm nhũn hoặc chuyển màu đen, rễ bị thối nhũn, xuất hiện ruồi nấm (fungus gnats), đất có mùi chua ủng | mép lá khô giòn chuyển màu nâu, lá rũ xuống nhưng tươi tỉnh lại chỉ sau vài giờ được tưới nước, đất co lại tách rời khỏi thành chậu, nhấc chậu thấy rất nhẹ |
| Cách khắc phục: ngừng tưới ngay, kiểm tra bộ rễ, thay sang giá thể đất khô mới nếu rễ đã bị thối, kéo dài khoảng cách giữa các lần kiểm tra | Cách khắc phục: tưới đẫm hoàn toàn (ngâm đáy chậu trong nước 20-30 phút nếu đất bị trơ không ngấm nước), rút ngắn khoảng cách kiểm tra lại một chút |

Cây bị rũ lá trong khi đất vẫn **ướt** có nghĩa là bộ rễ đã bị tổn thương: tuyệt đối không tưới thêm nước.

## Kỹ thuật tưới nước
- Tưới từ từ khắp bề mặt đất cho đến khi nước chảy ra ở lỗ đáy chậu; chờ một lát, sau đó đổ bỏ nước đọng trong đĩa hứng sau khoảng 15 phút.
- Dùng nước ở nhiệt độ phòng. Cây đuôi công (calathea) và một số loài dương xỉ dễ bị cháy nâu đầu lá nếu tưới bằng nước cứng hoặc nước đã làm mềm bằng muối; dùng nước mưa hoặc nước lọc sẽ tốt hơn.
- Tưới thẩm thấu ngược từ đáy (ngâm đáy chậu trong khay nước khoảng 20-30 phút) rất hiệu quả với các chậu nhỏ và đất bị khô co rút lại; thỉnh thoảng hãy tưới từ trên xuống để rửa trôi muối khoáng tích tụ.
- Chậu tự tưới: châm thêm nước vào bình chứa khi đã cạn và thỉnh thoảng cứ để bình chứa cạn khô trong một hoặc hai ngày để rễ cây được hô hấp; không dùng loại chậu này cho cây mọng nước.
FILE:references/adjustment-factors.md
# Các hệ số điều chỉnh

Khoảng cách kiểm tra = số ngày cơ sở (theo nhóm cây) x kích thước chậu x chất liệu chậu x ánh sáng x độ ẩm x mùa, được làm tròn và giới hạn trong khoảng 1..45 ngày. Dưới đây là các hệ số nhân được sử dụng trong `scripts/watering_planner.py`.

| Yếu tố | Giá trị | Hệ số nhân | Lý do |
|---|---|---|---|
| Đường kính chậu | dưới 10 cm | 0.6 | ít đất, khô chỉ sau vài ngày |
| | 10-13 cm | 0.8 | |
| | 14-19 cm | 1.0 | mức tham chiếu chuẩn |
| | 20-27 cm | 1.3 | nhiều đất hơn nên giữ nước lâu hơn |
| | từ 28 cm trở lên | 1.6 | chậu lớn vẫn còn ướt ở đáy rất lâu sau khi bề mặt đã khô: cần kiểm tra sâu xuống dưới |
| Chất liệu | nhựa, tráng men, gốm sứ, kim loại | 1.0 | thành chậu không thoát hơi nước |
| | đất nung (terracotta) / đất sét không tráng men | 0.75 | thành chậu thấm hút và làm bay hơi nước |
| | túi vải trồng cây (fabric grow bag) | 0.7 | khô nhanh từ mọi phía |
| | chậu tự tưới | 1.5 | bình chứa cấp ẩm dần cho đất; hãy kiểm tra bình chứa nước thay vì mặt đất |
| Ánh sáng | thấp (cách cửa sổ trên 2 m, phòng hướng Bắc) | 1.4 | cây ít phát triển, tiêu thụ ít nước |
| | trung bình | 1.0 | |
| | ánh sáng gián tiếp mạnh | 0.85 | |
| | nắng chiếu trực tiếp lên lá | 0.7 | |
| Độ ẩm | thấp (đang bật sưởi, dưới ~35 %) | 0.85 | đất và lá mất nước nhanh hơn |
| | bình thường | 1.0 | |
| | cao (phòng tắm, có máy tạo ẩm) | 1.15 | |
| Mùa | mùa xuân | 1.0 | |
| | mùa hè | 0.85 | |
| | mùa thu | mức giữa của mùa xuân và mùa đông | đà tăng trưởng chậm lại khi ngày ngắn đi |
| | mùa đông | hệ số giãn cách mùa đông theo từng nhóm cây (từ x1.2 đến x2.5) | |

Phân chia mùa: ở Bắc bán cầu, tháng 12-tháng 2 là mùa đông, tháng 3-tháng 5 là mùa xuân, tháng 6-tháng 8 là mùa hè, tháng 9-tháng 11 là mùa thu; ở Nam bán cầu lệch đi sáu tháng. Nếu đặt cây ngay cạnh lò sưởi hoặc trong phòng kính có sưởi ấm, hãy chọn mức độ ẩm "low" (thấp) ngay cả vào mùa đông.

## Khả năng thoát nước
Chậu không có lỗ thoát nước là nguyên nhân đơn lẻ lớn nhất gây thối rễ. Cách tốt nhất: giữ nguyên cây trong chậu nhựa ươm cây đặt lọt bên trong chậu trang trí và đổ hết nước đọng ở chậu ngoài sau khi tưới 15 phút. Nếu bắt buộc phải trồng trực tiếp trong chậu không có lỗ, chỉ tưới khoảng một nửa lượng nước thông thường và nghiêng nhẹ chậu để kiểm tra xem có nước đọng dưới đáy không. Bộ lập lịch sẽ gắn cờ trường hợp này ở mức cảnh báo HIGH.

## Lượng nước tưới
Khoảng 15-25 % thể tích chậu, tưới cho đến khi thấy nước thoát ra ở lỗ đáy. Bộ lập lịch ước tính thể tích chậu từ đường kính (giả định chậu thành đứng có chiều cao bằng khoảng 0.9 lần chiều rộng), vì vậy chậu 15 cm cần khoảng 450 ml nước, chậu 24 cm cần khoảng 1.75 lít. Cây mọng nước và cây chịu hạn cũng cần được tưới đẫm mỗi lần như vậy, chỉ là tần suất thưa hơn.

## Tinh chỉnh sau hai hoặc ba tuần
- Đất vẫn còn ẩm ở hầu hết các lần kiểm tra: hãy kéo dài khoảng cách kiểm tra của cây đó thêm 25-50 % (hoặc chuyển thông số ánh sáng sang "low" nếu cây đặt xa cửa sổ).
- Đất khô cong ở mọi lần kiểm tra và lá cây bị rũ xuống: rút ngắn khoảng cách kiểm tra đi 25 %.
- Hãy cập nhật trực tiếp các thay đổi này vào tệp CSV (ví dụ: đổi nhóm cây hoặc mức ánh sáng) rồi chạy lại công cụ, thay vì cố ghi nhớ các trường hợp ngoại lệ trong đầu.
- Chạy lại kế hoạch khi bắt đầu bật hoặc tắt hệ thống sưởi, khi bạn thay chậu mới (chậu lớn hơn = khoảng cách dài hơn), hoặc khi đổi vị trí đặt cây.

## Các trường hợp nằm ngoài quy tắc tính khoảng cách
- Cây mới thay chậu: tưới đẫm một lần ngay sau khi thay chậu, sau đó chờ đến khi đất đạt đúng điều kiện trong quy tắc mới tưới tiếp.
- Các loại củ ngủ đông và xương rồng trong giai đoạn nghỉ đông lạnh giá (5-12 C): hầu như không cần tưới nước; chỉ cần kiểm tra mỗi tháng một lần là đủ.
- Bón phân: chỉ thực hiện vào mùa xuân và mùa hè, pha loãng bằng một nửa liều lượng khuyến cáo, bón vào đúng ngày tưới nước.
FILE:templates/watering-plan.md
# Kế hoạch chăm sóc cây: <nhà / phòng>

**Giai đoạn:** <2026-10-30 đến 2026-12-10>   **Ngày kiểm tra:** <Thứ Hai và Thứ Năm, 5-10 phút>
**Điều kiện:** <Bắc bán cầu, đang bật sưởi (không khí khô)>   **Đánh giá lại vào:** <2026-11-16>

## Việc cần làm ngay
- <Lan ý (Peace lily): không có lỗ thoát nước - hãy chuyển cây sang chậu nhựa ươm đặt lọt bên trong chậu bọc ngoài; đổ bỏ nước đọng ở chậu bọc ngoài sau khi tưới 15 phút>
- <Spike (xương rồng): đã quá hạn - cần kiểm tra ngay vào Thứ Hai>

## Lịch trình hàng tuần
| Ngày | Kiểm tra các cây sau |
|---|---|
| <Thứ Hai> | <dương xỉ, đuôi công calathea, lan ý, húng quế, hoa lan, trầu bà pothos, xương rồng (mỗi Thứ Hai cách tuần trong tháng Mười Hai)> |
| <Thứ Năm> | <dương xỉ, đuôi công calathea, lan ý, húng quế, hoa lan, trầu bà lá xẻ monstera; lưỡi hổ mỗi 2-3 tuần> |

## Bảng hướng dẫn nhanh
| Cây | Tưới khi | Lượng nước ước tính | Ghi chú |
|---|---|---|---|
| <Monty (monstera)> | <khô 1/3 lớp đất mặt> | <~1.75 l cho đến khi thoát nước> | <cửa sổ hướng Đông nhiều sáng> |
| <Sansa (snake plant)> | <khô 3/4 độ sâu đất> | <~450 ml> | <Tháng Mười Hai: mỗi 3 tuần> |

## Cách kiểm tra
- Ấn ngón tay vào đất đến độ sâu ghi trong cột "Tưới khi"; chỉ tưới nếu đất đã khô đến độ sâu đó.
- Tưới cho đến khi nước chảy ra ở đáy chậu, đổ hết nước trong đĩa hứng sau 15 phút.
- Đất ướt + lá vàng = thừa nước: bỏ qua lượt tưới và báo lại cho tôi.

## Cảnh báo
- <Fernando (dương xỉ Boston) trồng trong chậu đất nung bị khô chỉ sau 2 ngày khi bật sưởi: hãy thêm một buổi kiểm tra vào Thứ Bảy hoặc chuyển sang chậu nhựa>
- <Húng quế cần được kiểm tra hàng ngày trên bệ cửa sổ đầy nắng; hãy tưới ngâm đáy chậu mỗi khi bạn đi ngang qua>

## Khi đánh giá lại
Đối với mỗi cây, hãy ghi chú xem đất thường vẫn còn ẩm (cần giãn cách dài hơn) hay đã khô kiệt (cần rút ngắn lại) vào các buổi kiểm tra; tôi sẽ cập nhật lại kế hoạch.
FILE:examples/plants.csv
name,plant,pot_cm,pot_material,light,drainage,last_watered,notes
Monty,monstera,24,plastic,bright,yes,2026-10-28,living room by the east window
Pothos shelf,pothos,14,glazed,medium,yes,2026-10-27,trailing from the bookshelf
Sansa,snake plant,17,terracotta,low,yes,2026-10-20,hallway corner
Zed,zz plant,20,plastic,medium,yes,,new from the shop
Fernando,boston fern,20,terracotta,bright,yes,2026-10-29,bathroom shelf
Cal,calathea,15,plastic,medium,yes,2026-10-28,bedroom
Spike,cactus,10,terracotta,direct,yes,2026-10-15,south windowsill
Peace lily,peace lily,18,glazed,low,no,2026-10-26,decorative pot with no hole
Orchid,phalaenopsis,12,plastic,bright,yes,2026-10-25,kitchen window
Basil,basil,13,terracotta,direct,yes,2026-10-29,kitchen windowsill
FILE:examples/plan-output.md
# Kế hoạch tưới cây trong nhà: 2026-10-30 đến 2026-12-10

Bán cầu: Bắc   Mùa lúc bắt đầu: mùa thu   Độ ẩm: thấp   Ngày kiểm tra: Thứ Hai, Thứ Năm   Số lượng cây: 10

Kiểm tra không đồng nghĩa với tưới nước: hãy chạm tay cảm nhận độ ẩm của đất và chỉ tưới khi quy tắc của cây báo đã đến lúc.

## Danh sách cây

| Cây | Nhóm | Chậu | Ánh sáng | Kiểm tra mỗi | Tưới khi | Lượng nước ước tính | Số lần kiểm tra |
|---|---|---|---|---|---|---|---|
| Monty (monstera) | top_dry | nhựa 24 cm | sáng | 7 d (winter: 9 d) | khô 1/3 lớp đất phía trên (khoảng 3-5 cm đối với chậu 15 cm) | ~1750 ml (cho đến khi thoát nước) | 6 |
| Pothos shelf (pothos) | top_dry | tráng men 14 cm | trung bình | 7 d (winter: 8 d) | khô 1/3 lớp đất phía trên (khoảng 3-5 cm đối với chậu 15 cm) | ~350 ml (cho đến khi thoát nước) | 6 |
| Sansa (snake plant) | dry_tolerant | đất nung 17 cm | thấp | 16 d (winter: 21 d) | đất khô ít nhất 3/4 độ sâu từ trên xuống | ~450 ml (cho đến khi thoát nước) | 3 |
| Zed (zz plant) | dry_tolerant | nhựa 20 cm | trung bình | 20 d | đất khô ít nhất 3/4 độ sâu từ trên xuống | ~750 ml (cho đến khi thoát nước) | 2 |
| Fernando (boston fern) | evenly_moist | đất nung 20 cm | sáng | 2 d (winter: 3 d) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để khô hoàn toàn | ~1000 ml (cho đến khi thoát nước) | 12 |
| Cal (calathea) | evenly_moist | nhựa 15 cm | trung bình | 3 d (winter: 3 d) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để khô hoàn toàn | ~450 ml (cho đến khi thoát nước) | 12 |
| Spike (cactus) (quá hạn: kiểm tra ngay ngày đầu tiên) | succulent | đất nung 10 cm | trực tiếp | 6 d (winter: 9 d) | đất khô hoàn toàn đến tận đáy (rút đũa gỗ ra thấy sạch và khô) | ~100 ml (cho đến khi thoát nước) | 6 |
| Peace lily (peace lily) | evenly_moist | tráng men 18 cm, KHÔNG lỗ | thấp | 4 d (winter: 5 d) | lớp đất mặt 1-2 cm vừa chớm khô; không bao giờ để khô hoàn toàn | ~375 ml, không tưới nhiều hơn | 12 |
| Orchid (phalaenopsis) | orchid | nhựa 12 cm | sáng | 5 d (winter: 6 d) | rễ màu xám bạc và vỏ thông khô; ngâm 10 phút, để ráo hoàn toàn | ngâm 10 phút | 11 |
| Basil (basil) | herb | đất nung 13 cm | trực tiếp | 1 d (winter: 1 d) | lớp đất mặt 1-2 cm đã khô | ~350 ml (cho đến khi thoát nước) | 12 |

## Lịch kiểm tra

| Ngày | Thứ | Mùa | Cây cần kiểm tra |
|---|---|---|---|
| 2026-11-02 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike, Zed |
| 2026-11-05 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-11-09 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-11-12 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
| 2026-11-16 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-11-19 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-11-23 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike, Zed |
| 2026-11-26 | Thu | autumn | Basil, Cal, Fernando, Monty, Orchid, Peace lily |
| 2026-11-30 | Mon | autumn | Basil, Cal, Fernando, Orchid, Peace lily, Pothos shelf, Spike |
| 2026-12-03 | Thu | winter | Basil, Cal, Fernando, Monty, Orchid, Peace lily, Sansa |
| 2026-12-07 | Mon | winter | Basil, Cal, Fernando, Peace lily, Pothos shelf, Spike |
| 2026-12-10 | Thu | winter | Basil, Cal, Fernando, Monty, Orchid, Peace lily |

## Cảnh báo

| Mức độ | Cây | Lưu ý |
|---|---|---|
| HIGH | Peace lily | chậu không có lỗ thoát nước: nước đọng ở đáy làm thối rễ. Hãy thay chậu có lỗ, hoặc trồng cây trong chậu nhựa ươm đặt lọt bên trong chậu bọc ngoài và đổ hết nước đọng sau khi tưới 15 phút |
| LOW | Fernando | chậu đất nung làm cây này khô rất nhanh; đổi sang chậu nhựa hoặc chậu gốm tráng men sẽ giúp giữ ẩm đều hơn |
| LOW | Fernando | các ngày kiểm tra cố định khiến một số lượt kiểm tra bị trễ hơn một ngày (ví dụ: đến hạn 2026-11-07, lịch xếp vào 2026-11-09); hãy thêm một ngày kiểm tra trong tuần hoặc sờ thử đất xen kẽ giữa các buổi |
| LOW | Basil | các ngày kiểm tra cố định khiến một số lượt kiểm tra bị trễ hơn một ngày (ví dụ: đến hạn 2026-11-03, lịch xếp vào 2026-11-05); hãy thêm một ngày kiểm tra trong tuần hoặc sờ thử đất xen kẽ giữa các buổi |

Các khoảng thời gian trên giả định rằng cây đã bén rễ ổn định trong giá thể thoát nước tốt. Sau 2-3 tuần, hãy kéo dài khoảng cách kiểm tra nếu thấy đất vẫn còn ẩm ở hầu hết các lần kiểm tra, hoặc rút ngắn lại nếu lúc nào kiểm tra đất cũng đã khô kiệt.
FILE:scripts/watering_planner.py
#!/usr/bin/env python3
"""Houseplant watering schedule planner (Python 3.8+ standard library only).

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

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

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

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


class InputError(Exception):
    pass


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


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


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


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


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


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


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


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


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


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


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


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


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


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

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


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


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