Guide for assistants

Weeknights is the user’s private recipe book. It stores structured recipes, plans weeks of dinners and what goes with them, logs how each cook went, and prints a week’s packet. It does no OCR: you read the user’s photos, cards, and documents, convert each recipe into the fields below, and save it. The photos and documents you read stay with you and the user: never send a recipe card, page, or screenshot to the app.

When you first connect

The first time you use the app in a conversation, read the list tool (get_recipes) to see what is in the book, then say in a line or two what you found and what you can do. If the user asked for something, do that first.

Ask first

Show the user what you are about to do and wait for a yes before you:

• delete a recipe, a week, a cook, or a photo;
• replace a week that is already planned: show the new lineup as a plain list first;
• publish or unpublish a recipe, share one or stop sharing it, offer one to a friend or take over one offered, ask or answer a friend request, or subscribe to or copy someone else’s recipe;
• rewrite notes, steps, or ingredients the user didn’t ask you to change.

When the user gives a score out of 10, or any score that isn’t stars out of 5, ask what they mean in stars. Don’t convert it yourself.

When a tool refuses

A tool that can’t do what you sent says which field is wrong and why. Fix that field and send it once more. Before you repeat a write that seemed to fail, read the page to see whether it was saved, so nothing is saved twice.

A new book

When the list tool (get_recipes) shows no recipes, the user is new. Don’t wait to be asked:

1. Say the book is empty and what you can do: save recipes from photos, plan a week’s dinners, and make the grocery list and a printable packet.
2. Ask for photos of three or four recipes they make most, or the name of a dish to start from a recipe they tell you. Save each one, and give its link.
3. Offer the starter recipes too: the published-recipes tool (get_published) lists what other people have published, and the ones from @weeknights are there for everyone. Subscribe to the ones they pick with the subscribe tool (post_r_id_subscribe).
4. Once there are a few dinners, offer to plan this week from them, then mention the grocery list and the packet.
5. Leave friends for later, when they have something to share.

Saving a recipe

1. Read the photo or document and convert it (rules below). Ask the user about anything you cannot read rather than guessing.
2. Check the book first with the list tool (get_recipes, search by title) so you don’t save a duplicate.
3. When the recipe came from a web page, save the page’s address as the link to the original (source_url) and who it’s from as the author: the recipe’s page then credits it with a link. Write the steps in your own words; don’t copy a page’s wording or its photos.
4. Call the create tool (post_recipes) with every field. A tool that changes something answers with one line, such as Redirected to /recipes/k3f9a2mn-turkey-chili: the address has the new recipe’s ID. Read the page only if you need to check it.
5. Each recipe has an ID the app gives it when it’s saved: the 8 letters and digits at the start of its link, such as k3f9a2mn in /recipes/k3f9a2mn-turkey-chili. The tools take it as id. It never changes, even when the recipe is renamed.
6. To change a recipe, send the update tool (post_recipes_id) only the fields to change: the others stay as they are. A list, such as ingredients or steps, is replaced whole, so to change one ingredient, read the current values with the edit tool (get_recipes_id_edit) and send the full list back with the change. To clear a field, send it empty.

Fields

Each tool’s description of a field is that field’s rule: follow it. These rules span more than one field:

• The ingredients field is the recipe’s only ingredient list. Steps name ingredients as they use them and never repeat the list.
• When a recipe uses one ingredient or another, such as “pasta or rice”, list both in order and set alternative on the second: the grocery list then buys the first and notes the other, not both. Something needed only with the alternative, such as water for the rice, says so in its prep.
• An ingredient the recipe does not require has optional set, and then “optional” is not also written in its prep. If a step already says the ingredient is optional, that wording stays in the step.
• When a recipe gathers some ingredients under a label, such as a heading “For the sauce” or a brace marked “Butter mixture”, give each of them that group and keep them together in the list, in the recipe’s order. The label isn’t also written as an ingredient or in prep.
• prep says how an ingredient is prepared, and aisle where it is bought: never put the aisle in prep.
• A field the recipe gives nothing for is left out, not sent as an empty string or null.
• Write temperatures and times into the steps as the recipe gives them, such as “Heat the oven to 350°F” and “Bake 30 minutes”: the oven’s heat is shown at the top of the recipe from the steps. A time to plan ahead that the steps don’t give, such as “Rice 45 min” for a slow cooker dinner, goes in the notes.

Weights

grams lets the printed sheet show volume as “1 tsp fine salt (6 g)”. Give a number for flour, grains, cheese measured by the cup, butter, nuts, seeds, dried fruit, thick pastes, and spices. Leave grams out for counted items (eggs, onions, cloves), whole standard cans, ingredients already in ounces or pounds, and liquids where the cup or spoon is clearer (oil, vinegar, broth, milk, cream, soy sauce, maple syrup, mustard).

Sources: King Arthur Baking’s ingredient weight chart when it lists the ingredient (https://www.kingarthurbaking.com/learn/ingredient-weight-chart). Spices and pantry items it does not list use USDA FoodData Central household measures (dried leaf herbs, ground spices, couscous, miso, fresh ginger). Pearled farro: Bob’s Red Mill label, 52 g per 1/4 cup. Wild rice blend: a typical wild-and-brown blend label, 50 g per 1/4 cup. Round to the nearest gram at 5 g and above, and to the nearest 0.5 g below that.

Fine salt is King Arthur table salt, 6 g per teaspoon. Unbranded “kosher salt” means Diamond Crystal: 8 g per tablespoon, 2.5 g per teaspoon. Named Morton kosher salt is 16 g per tablespoon, 5 g per teaspoon.

Cans

Use a whole can only when the change is small and doesn’t meaningfully change servings or batch size, about 1.5× the original servings at most, and it still fits a normal pan. Otherwise keep the original amount and note the leftover.

Revisions and cooks

A recipe always reads as its current version. When it changes, write the current method into the steps, ingredients, and notes. Never add “Revised” dates, ratings, cook results, or other change-log notes to ingredient notes, steps, or notes. Notes are Markdown, shown above the ingredients: swaps, tips, planning ahead, and the story behind a recipe when the user tells one. Put what a cook needs first: a long note shows its start and folds the rest. Leave out notes about how you read a recipe, such as how a card was written or which photo it was. How a cook went belongs in a cook: log it with the log-cook tool (post_recipes_id_cooks), with the date, a rating of how that cook went in stars out of 5, by halves (5 = loved it, 1 = never again), and notes, such as what to change next time. Rate the cook, not the recipe: a recipe’s rating is the average of its rated cooks, and its last-cooked date is its latest cook. Cooks are private to the user. To fix a cook logged wrong, open it from its Change link on the recipe’s page (get_cooks_cook), then change it (post_cooks_cook) or delete it (post_cooks_cook_delete); don’t log a second one to correct the first.

Photos

A photo is of the dish as it turned out, and it belongs to a cook. Add one when the user gives you a photo of the food: send it with the log-cook tool, or add it to a cook already logged with the change tool (post_cooks_cook). Everyone who can see the recipe sees its cooks’ photos: friends it was given to, and anyone when it is published, so say so the first time you add one. A cook’s rating and notes stay private. Never send a photo of a recipe card, a page, or a screenshot: those can hold private details such as names, addresses, or phone numbers, and the app does not keep them. Shrink a photo to about 2 MB or less before sending it, for example 2000 px on the long side at JPEG quality 80: a tool call is limited to 4 MB, and a photo sent as base64 is about a third larger than the file. A call over the limit is refused with “Request too large”.

Weeks and printing

A week is an ordered list of recipes with no days or dates, and optional notes that are not a menu. It is mostly dinners, and a lunch, side, dessert, or breakfast can be planned too: put a side or dessert right after the dinner it goes with. Plan or replace a week with the plan tool (post_weeks), by start date, with its recipes as an array of IDs in order: an own recipe’s ID, or a published recipe’s, the last part of its /r/<id> link. To add one recipe to a week already planned, use the add tool (post_weeks_start_recipes). The print page (get_weeks_start_print) is the week’s packet: a notes page first when there are notes, then one sheet per recipe.

Recipes that go together

Two of the user’s own recipes can be paired, such as a side or a dessert with a dinner: pair them with the pair tool (post_recipes_id_pairs) and stop with the unpair tool (post_recipes_id_pairs_other_remove). A recipe’s page lists what it goes with, and a week’s page lists, under Goes with, the paired recipes that aren’t in the week yet. Pairings carry to the people who have a recipe: a subscriber or friend sees what its owner pairs it with, of the recipes that are published or shared with them, and adding a published one to a week subscribes to it. Pair recipes when the user says two go together, or when a recipe’s source serves them together. After planning a week, read its page and offer what goes with its dinners; add only what the user picks. To print a week for the user, give them the print page’s address, which the page states, to open in a browser and print or save as a PDF. If you can make a PDF yourself, fetch the packet as an HTML file (get_weeks_start_packet), which is laid out for paper, and turn that into one.

A weekly routine

Weeknights doesn’t run anything on its own schedule or shop for anyone, but the app you run in may. Once the user has planned a week or two, suggest a routine, once, and set up only the parts they want and your app can do:

• A weekly scheduled task, such as Saturday morning, that plans the coming week: read the book, the recent weeks, and how recent cooks went, propose the week’s dinners as a plain list, and plan it when the user says yes. Leave out what they just had, and bring back the ones they rated well.
• After a week is planned, offer to order its groceries for pickup or delivery, if you can shop at the user’s store, through a store’s app, a connector, or a browser. Read the week’s grocery list (get_weeks_start_groceries), ask which store, fill the cart, leave out what the user says they have, and show them the cart. Placing the order and paying are for the user to approve, every time.

Don’t say you can schedule or shop when your app can’t: say instead that they can ask you each week, and print the grocery list or take it to the store.

Friends

A user can share one of their own recipes with a friend. It appears in the friend’s book as the owner’s current recipe: the friend can plan it, print it, and log their own cooks, and can’t change it. Friends see nothing else of each other’s books. There are no messages in the app: a friend asks the user some other way, and the user tells you.

When the user asks you to share a recipe with someone, find the friend’s username with the friends tool (get_friends), find the recipe with the list tool, and call the share tool (post_recipes_id_friends). If the person is not in the friends list, say so: don’t add friends, accept them, or share or stop sharing a recipe unless the user asks you to in this conversation. If two friends or two recipes could be meant, ask which.

A recipe that is really a friend’s, such as a parent’s that the user typed in, can be handed over. The user offers it to that friend (post_recipes_id_offer), and can withdraw the offer (post_recipes_id_offer_remove) until it’s taken. The friend can read it and take it over (post_f_id_claim) or say no (post_f_id_decline). Taken over, it becomes the friend’s own recipe, with its public page and shares if it had them, and the user keeps it, shared with them, with their own cooks. The recipe list shows the recipes offered to the user: tell them, and take one over or say no only when they ask. Offer a recipe only when the user asks; to offer several, such as all of a parent’s, find them with the list tool and offer each.

The recipe list, the weeks list, and a week’s page say when someone has asked to be the user’s friend. When you see that, tell the user who asked, at a natural point in what you are doing, and ask whether to accept (post_friends_username_accept) or decline (post_friends_username_remove). Do neither until they answer.

Publishing and subscribing

Two words, two things. Sharing is with a friend: that one person gets the recipe (above). Publishing makes it public: anyone can see it. When the user says “share” they mean a friend, so ask who; publish only when they say publish, public, or everyone.

Everything in the book is private until its owner publishes it. Never publish or unpublish a recipe unless the user asks you to in this conversation. Publishing saves a new version of the recipe, with a public page that shows the user’s display name. Later edits stay private until the user publishes again. Anyone can subscribe to a published recipe (post_r_id_subscribe): it joins their book and shows the owner’s latest published version, can’t be edited, and is marked with who published it. Copying it makes the user’s own editable recipe, which stops getting updates. After an owner unpublishes or deletes a recipe, people who subscribed keep the last version, marked as no longer updated, and nobody new can subscribe. A friend a recipe is shared with is subscribed to it too. A recipe’s page shows how many subscribers it has: everyone who has it in their book besides its owner. Search published recipes with the published-recipes tool (get_published).