> For the complete documentation index, see [llms.txt](https://docs.kinwall.family/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinwall.family/using-kinwall/chores.md). # Chores For a push when someone adds a chore for you or Anyone, turn on **New chores** in this device's [notification settings](/using-kinwall/notifications.md#new-chores). It is off by default and separate from the daily chore reminder. Chores you add yourself do not notify you. ![Chores on the wall iPad, with leaderboard and streaks](https://4251322152-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2kP7ksVUPkKNBdqDQdkp%2Fuploads%2Fgit-blob-eaff11c3d66294e8703061dd1e8e609466907ebc%2Fipad-chores.png?alt=media) The Chores tab shows one column per family member plus **🌟 Anyone**. Each column has a progress ring, a "*N* pts today" total and that day's chore cards. The total counts the points that person earned that day, including **Anyone** chores they did; the **Anyone** column says how many points it gave out instead ("10 pts given out"). Cards read in order: chores still to do first, those with a start time by time, then the done ones. A start time that has gone by says so, such as "8:00 AM (late)", on the card and on the Board's Today card. On phones, members with nothing due are listed on one line ("Nothing due: Leo") instead of showing as empty cards. When the family is filtered to one person (the family sheet on a phone, or an avatar on the wall), the tab shows that person and **Anyone**. A display pinned to one person hides **Anyone** only if **Also show things for everyone** is off. Don't use chores? An admin can turn off **Chores & points** in **Settings → General** (tap **Change** under **Features**). It's hidden on every screen (rewards and the sticker book too); nothing is deleted. See [Features](/settings-reference/general.md#features). ## Completing chores * **Tap** a card to mark it done (with a check and a small confetti burst). Tapping a done chore asks **Mark "…" not done?** first, so a stray tap can't take points back. * A **date strip** lets you look at 4 days back and 9 days ahead. Beneath each date, **N left** counts unfinished chores; an hourglass means some are waiting for a parent’s OK. **✓ Done** means every chore for that date is approved. Dates without chores stay blank. The counts follow the member filter, including Anyone chores unless this display hides shared chores, and update when chores change. Flexible goals stop adding work on other dates once their interval is full; actual ticks stay on the dates they happened. You can complete chores for any day shown. * Completing a chore credits the chore's assignee. Ticking off an **Anyone** chore on the Chores tab asks **Who did it?**: pick the person who earns the points, or **Nobody in particular**. It doesn't ask when the family is filtered to one person or the display is pinned to one; the chore counts for that person. Through the API, an **Anyone** chore completed without naming anyone counts for the device's owner: a kid's device, or a grown-up's own phone or computer (picked under **Whose device is this?**). Unticking never asks. A done **Anyone** chore says who got the points, such as "Done by Sam", or "Done by nobody in particular". * To edit a chore, tap **✏️ Edit chores** at the top, then tap the chore. While it's on, a tap edits instead of ticking; tap **Done** to go back (it also turns off when you leave Chores). On a computer you can also right-click a chore, or tab to it and use its **Edit** button. Adding, editing and deleting chores works on parent devices only: wall screens and kids' devices tick chores off (and undo), with no **+** button and no editor. * A link that opens a chore to tick off (such as one from the app's Chores widget) asks first, for example **Mark "Dishes" done for Leo?**, unless it opens **Who did it?** or the chore's checklist anyway. * Ticking a chore off (or undoing it) works while offline: the tick shows at once and waits on the device, even mid-outage. The header's crossed-out cloud icon (next to the bell) shows how many changes are still waiting to sync. See [Offline shopping](/using-kinwall/lists.md#offline-shopping) for how this works. ## Ticking chores off from someone's day A person's day (their snapshot) lists their chores for today, plus **Anyone** chores, each with its start time and points ("8:00 PM · 5 pts"). Under the greeting it says what they have to spend and what they're saving for ("⭐ 18 to spend · Saving for 🍦 Ice cream trip, 18 / 50"), which opens their Rewards. Tap a chore to mark it done, or (after confirming) not done, the same as on the Chores tab. An **Anyone** chore done from someone's day counts for that person. A chore with a checklist that still has open items opens the checklist first, in [Get stuff done](/using-kinwall/lists.md#get-stuff-done). On a phone, open someone's day from the family button at the top left, then tap the person. ## Late chores On a short **Chores today** card, the late-chores count may be inside **+N more**. Open it to reach the count and its list. A chore that isn't ticked off on its day doesn't disappear right away: for 7 days it stays on the Board as late. For a repeating chore, that's its last time before today: **Feed the fish** missed yesterday is late, but not the days before, so a missed week doesn't stack up seven copies. The Board's chores spot (the **Chores today** card, the Chores tile, or the row on **Today**) shows **⏰ 2 late chores**. Tap it for a list of them, each with who it's for and the day it was due ("Was due Thu, Nov 5"). Tap **Done** to tick one off for that day. It earns the [late completion credit](#points-late-completion-credit), or waits for a parent's OK like any other tick. After 7 days it drops off the Board, since a wall screen or kid's device can't tick it any more; a parent's device can still tick it on its day on the Chores tab. To drop a late one-time chore instead, go to its day on the Chores tab and delete it. * A repeating chore only ever shows its last time, and the next time takes its place once that day passes. Once it's ticked off, earlier misses stay on the Chores tab's calendar, which shows each day's open count. * A chore with a goal ("3 times a week") isn't late for a day off. * A late chore with a [checklist](#checklists) that still has open items opens Chores on its day with the checklist, to tick them off there. Finishing it ticks the chore off for that day. * A late chore ticked and waiting for a parent's OK isn't late any more; it's in the approvals list. * The count follows who the Board shows, like the rest of its chores: on a kid's device, only theirs and **Anyone**. ## Creating and editing Tap **+** (Add chore). The sheet has: | Field | Notes | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Title**, **Emoji** | | | **Points** | **−** and **+**, or type a whole number. The same control as in the reward sheet and **Say yes…**. | | **Assign to** | **🌟 Anyone**, one member, or several. See [Chores for several people](#chores-for-several-people). | | **Repeat** | **Once**, **Daily**, **Weekly** or **Custom…**. Custom repeats every N days, weeks, months or years. | | **On** (Weekly) | Pick weekdays. With none picked, it repeats on the weekday of its start date. A new chore pre-selects today. | | **Starts** (repeating) | The first date the schedule can happen. It also anchors the interval. Existing chores without a start date keep their original creation day. | | **Ends** (repeating) | **Never**, **On a date** (inclusive), or **After a number of occurrences**. Occurrences count scheduled dates from the start, including dates already passed. | | **Due date** (Once) | The day a one-off chore is due. | | **Checklist (optional)** | A list that has to be fully ticked before the chore can be completed. See [Checklists](#checklists). | | **Start time (optional)** | When the chore should start, such as 4:00 PM. One time for every day it's due. It shows on the chore and on the Board's Today card. **No start time** clears it. | | **Timer (optional)** | How long it takes, such as 20 min. Tapping the chore starts a timer that long. See [Start time and timer](#start-time-and-timer). Not shown with an activity, which times itself. | | **Do an activity (optional)** | One of the family's [activities](/using-kinwall/nooks/activities.md) and **Minutes** (1–60, default 5). Playing it completes the chore. See [Activity chores](#activity-chores). Shown once an activity is installed. | | **Needs a parent's OK** | **Default**, **Yes** or **No**. See [Parent approval](#parent-approval). With an activity, also **Needs a parent's OK even for timed play**. | ### Chores for several people Pick more than one person under **Assign to** to give each of them their own copy of the chore, such as **Set the table** for Maya and Leo but not Sam. Each copy shows in that person's column and is ticked off on its own: Maya finishing hers doesn't tick off Leo's, and each earns the points. **🌟 Anyone** is different: one chore that whoever does it first gets the points for. The copies stay linked. Editing one and tapping **Save** changes them all, and tapping a person under **Assign to** before saving adds or removes their copy. Down to one person, it's an ordinary chore again. **More… → Delete chore…** deletes every copy. Copies that were ever done keep their history and points, as for any chore. **Custom…** adds a repeat interval and unit. Weekly schedules let you choose weekdays and which day begins each week. Monthly schedules let you pick several **Days of the month** (such as 1, 5 and 24), or several **Weekdays of the month** (such as First Monday and Last Friday). Open the picker, choose all the dates or combinations you need, and tap **Done**. With no numbered dates picked, the chore repeats on the day of its start date. Weekday schedules need at least one choice. Months without a picked date or weekday skip that occurrence; if two choices land on the same day, the chore is only due once that day. Yearly schedules use the month and day of the start date; February 29 only occurs in leap years. The editor shows upcoming dates when a start date is set. ### A number of times per interval Choose **Times per interval…** for a flexible goal, such as **Practice piano — 3 times per week** or **Water plants — 2 times every 3 days**. Pick **Times**, **Every**, days/weeks/months, and a start date. You choose which days to do it; each chore counts **at most once per day**, with points for each completion. The card shows progress such as **1 of 3 done this week**. Weekly intervals begin on **Weeks begin on**. Monthly intervals begin on the first of the month; multiweek and multimonth cycles are anchored to the week or month containing the start date. Day intervals start on the chosen date. The first interval can be shorter when the start is partway through a week or month. Unfinished progress does not carry over. Monthly targets allow at most 28 completions per month in the interval so February has enough days. When the target is met, the card says **Goal reached** and offers no extra tick for another day in that interval. Today's actual tick can still be undone. To undo a different day, open that day in the date strip; undo makes room in the interval again. Pending approvals reserve places until a parent approves or rejects them. **Anyone** goals share one target for the household. Unchosen days do not break a streak; the target is checked at the interval's end. Goals can end on a date, but do not use the scheduled repeat's occurrence limit. ### Alternating weekly duties For dishes every day, with Maya doing one week and Leo the next: 1. Add **Dishes** for Maya. Choose **Custom… → Repeat every 2 Weeks** and select all seven weekdays. 2. Set **Weeks begin on** to Monday, and **Starts** to the Monday of Maya's first week. 3. Add **Dishes** for Leo with the same settings, starting the following Monday. Each child sees a daily chore during their assigned week and none during the other week. Select just Monday for a chore that needs completing once every other week instead. The two chores are edited separately; the app does not automatically rotate a single chore between people. Chores created through the API or MCP can use other RRULE options. The editor keeps unsupported rules intact when you change unrelated details; choosing another repeat option replaces the rule. Recurring chores without an explicit start date use their creation day in the household timezone. Chores repeat daily or slower: repeats within a day and schedules that never happen are refused. **More… → Delete chore…** (in the chore's edit sheet) removes the chore from every list. If it was ever done, its history stays: points already earned from it are kept, it still counts on [profiles](/using-kinwall/profiles.md), and it stays in the data export. A chore that was never done is removed completely. ## Checklists A chore can have a **checklist**: one of your [lists](/using-kinwall/lists.md). Any kind of list works, but a **reusable** list fits best, such as "Bedtime routine: pick out clothes, shower, pajamas, brush teeth". Pick it under **Checklist (optional)** when you add or edit the chore. * The chore card shows the progress, for example `☑ 2/4 Bedtime`, until the chore is done. * Tapping the chore while items are still open opens the checklist straight in [Get stuff done](/using-kinwall/lists.md#get-stuff-done), full screen, instead of completing it: one item at a time, or the whole list. * Ticking the last item completes the chore the usual way (points, and a parent's OK when the chore needs one), then shows **All done! 🎉** with what it earned, such as "⭐ 5 points for Leo". An **Anyone** chore that would ask **Who did it?** says **One more tap!** instead, with **⭐ Get the 5 points**, which asks who and completes it. Closing it (**✕**) before then leaves the chore as it was. * Completing the chore resets a reusable checklist, ready for next time. Other kinds of list stay as they are. * Add, reorder or change the checklist's items, notes and sub-steps on the list itself, under Lists. ### One list for several people A chore's checklist shows the list's items **assigned to the chore's person, plus the unassigned ones**. A chore for **Anyone** shows the whole list. So one "Bedtime" list can serve both Maya's and Leo's bedtime chores: * Give each child their own "Shower" and "Brush teeth" items (set **Assign to** in the item sheet). * Leave shared steps, like "Turn off the hall light", unassigned. Ticks are saved on the list itself. A shared item ticked by one child is ticked for the other too, while each child's own steps stay separate. Completing the chore resets only that person's items and the shared ones. **API and MCP:** `listId` on `POST/PATCH /api/chores`, `checklist` progress on `GET /api/chores/day`, and `POST /api/chores/{id}/complete` answers **409** with `remaining` while items are open. In MCP, use the `list` argument on `create_chore` and `update_chore`. ## Start time and timer A chore can say when it starts and how long it takes, such as **🎹 Practice piano** at 4:00 PM for 20 minutes. Set either or both in the chore's sheet. * The card shows the start time ("4:00 PM · 5 pts · Daily") and, with a timer, **⏱ Start · 20 min**. * **Tap the card** to start the timer. It's the same [timer](/using-kinwall/timers.md) as the header's ⏱, named after the chore and its person ("Practice piano · 20 min, Maya"), so the header shows the time left and the card shows it too ("⏱ 12:34 left"). Tapping again while it runs doesn't start a second one. **Tap the check** to tick the chore off by hand, as with any chore. * Kids can start their own timers from their own device or from a wall screen. Starting a timer never ticks anything off. * When the time is up, the red banner has **Mark done** next to **OK**. **Mark done** opens Chores and ticks the chore off, the same as tapping its check: an **Anyone** chore asks **Who did it?** (unless the family is filtered to one person), a checklist with open items opens first, and a chore that needs a parent's OK waits for one. **OK** just stops the ringing; the chore stays open. * On the Board's **Today** card, chores with a start time or a timer get rows of their own among the day's events, in time order, such as "4:00 PM · 20 min 🎹 Practice piano" with the person's picture and **Start**. Chores with a timer and no start time come after the events. A chore drops off once it's done or waiting for a parent's OK. The rest of the day's chores stay in the **Chores** line under the events, which then reads **Other chores**. * Timers belong to the device they were started on, like every timer: one started on a kid's tablet rings there, not on the wall. **API and MCP:** `dueTime` (start time, `"HH:MM"`, 24-hour, household time) and `timerMinutes` (1–240) on `POST/PATCH /api/chores`; `null` clears either. `GET /api/board` lists today's chores with either in `timedChores`. In MCP, `create_chore` and `update_chore` take `dueTime` and `timerMinutes`. ## Activity chores A chore can be "*N* minutes of an activity", such as **🔤 5 min of Sight words**. Pick the activity and the minutes under **Do an activity (optional)**. Assignment, repeat and points work as for any chore. * The card shows the activity and the day's progress, for example `🔤 5 min of Sight words` and `2 of 5 min` with a small ring that fills as the minutes add up. * **Tap the card** to play. It opens the activity as the chore's person, so there's no **Who's playing?** For an **Anyone** chore, it asks unless the family is filtered to one person. * **Tap the check** to tick it off by hand, as with any chore. * While playing, the bar at the top shows the chore's progress ("Sight words: 3 of 5 min") with the same ring, filling second by second. When the time is reached, the ring turns into a check and the chore completes itself with a toast and confetti. There's no sound, because the activity may be speaking. * Kinwall does the timing, not the activity. Time counts in 15-second steps from the moment the activity opens: each step with a tap or answer in it counts, and a step with nothing in it counts 0. A tap or key press inside the activity, an answer saved or a word spoken all count as playing; opening it, sitting on it or tapping the bar around it don't. So a tablet left open earns nothing, while reading a question or thinking about an answer between taps still counts. Only seconds with the activity on screen count, and **Just playing** never does. The server also never counts more play than the real time that passed, so time can't be added faster than it's played. Older activities that don't pass their taps on to Kinwall count only the steps where they save an answer or speak; update them under **Activities → Get more activities**. * Leaving asks first. While a chore's time is counting, the **Leave?** question says so ("Your 10 minutes of Spelling practice will stop counting"). See [Activities](/using-kinwall/nooks/activities.md#playing-an-activity). * Play adds up across the day, per person and activity, in the household timezone, up to 4 hours a day. The chore completes once, on a day it's due, and earns its points, events and notifications like a tick. An **Anyone** chore goes to whoever reaches the time first. * If the activity is removed or turned off, the card says so. On a parent's device it reads "This chore's activity isn't installed." (or "Sight words is turned off.") with a link, **Install it from Get more activities** (or **Turn it on in Get more activities**), that opens **Activities → Get more activities**. A parent's device can still tick it off as usual. On a wall screen or a kid's device the card says "Do it with a grown-up, and a parent will okay it.", and ticking it always waits for a parent's OK (see [Parent approval](#parent-approval)), whatever the chore's own approval setting, so nobody earns the points for an activity that isn't there. The API enforces this too: `POST /api/chores/{id}/complete` from a display key comes back `pending: true`. * **Reset the time** (parent devices only): if you opened an activity as your child to check something and their time started counting, reset it. On **Chores**, tap **✏️ Edit chores** and then the chore, then pick **More… → Reset today's time…** (for an **Anyone** chore, filter to the person first). In the activity itself, tap the chore's progress at the top. Either way you confirm first. That person's time for that activity and day goes back to 0, and the 4-hour daily limit starts over with it. A chore their play already completed **stays done** with its points; untick it as well if it shouldn't count. Wall screens and kids' devices never see this. **API and MCP:** `pluginId` and `pluginMinutes` on `POST/PATCH /api/chores`, `activity` progress (`needSeconds`, `doneSeconds`, `available`) on `GET /api/chores/day`. The player sends `POST /api/plugins/{id}/playtime {member, seconds}` about every 30 seconds (at most 60 seconds a call; display keys may). It returns that person's activity chores due today with their progress. `DELETE /api/plugins/{id}/playtime?member=&date=` resets one person's time for a day (default today; full access only) and returns the same progress for that day. In MCP, `reset_activity_time` does the same; use the `activity` and `minutes` arguments on `create_chore` and `update_chore`. ## Parent approval A chore can wait for a parent's OK before it counts. Ticks from wall screens and kids' devices then land as **Waiting for OK** instead of done, and a parent approves them or sends them back with **Not yet**. **Turning it on** * Per person: **Their chores need a parent's OK** in the member's sheet (**Settings → Family**). Off by default. A **Grown-up** never has it: their chores only wait when the chore itself says **Yes**. * Per chore: **Needs a parent's OK** in the chore sheet. **Default** follows the person's setting (for an **Anyone** chore, the setting of whoever does it). **Yes** and **No** override it either way. * Activity chores approve themselves when timed play completes them. Turn on **Needs a parent's OK even for timed play** to have those wait too. Ticking one by hand follows the chore's normal setting. **How it works** * Ticking on a wall screen or kid's device (display keys, including the app's widgets and Watch) shows an hourglass and **Waiting for OK** on the card. The kid can tap it to untick while it waits. * A tick from a parent's device is approved straight away. * While it waits, the chore earns no points. It doesn't count toward streaks, the leaderboard, balances or the done counts on the Board, a person's day or widgets. The Board's chores card shows the waiting count (for example, `2 left · 1 ⏳`). * Parent devices get a notification ("Leo finished Make bed. Approve?") and a feed entry, once per chore and day. * Parent devices show a **To approve** count on the **Chores** tab and a **To approve** section at the top of the Chores screen. It shows the first two; **Show all (*****N*****)** opens the rest. The whole Chores screen scrolls, with the date strip staying at the top. **Approve** awards the points. **Not yet** opens a sheet for an optional note ("Please make the bed properly") and sends the chore back unticked. * After **Not yet**, the kid's card shows the note, such as "Not yet: Please make the bed properly", until they tick the chore again for that day. Their own devices (devices whose owner is that person, set in **Settings → Access**) get a notification with the note. On an activity chore, more play time doesn't send it back on its own; the kid ticks it. * Points are judged by when the chore was ticked, not when it was approved. A chore ticked on its day earns full points even if a parent approves it the next morning; one ticked late earns the [late completion credit](#points-late-completion-credit). **API and MCP** * `needsApproval` (`true`, `false` or `null` to follow the person) and `approveTimedPlay` on `POST/PATCH /api/chores`; `needsApproval` on `POST/PATCH /api/members` (always `false` for a member with `grownUp: true`). * `POST /api/chores/{id}/complete` answers `{ok, pending}`. `GET /api/chores/day` has `pending` and `rejection` (`{note, at}` or `null`); `completed` is true only once approved. * Parent devices only (admin keys): `GET /api/chores/pending`, `POST /api/chores/{id}/approve {date}` (answers `{ok, points}`), `POST /api/chores/{id}/reject {date, note?}`. * Webhooks: `chore.pending` when a tick waits, `chore.completed` only when it's approved, `chore.rejected` on **Not yet**. See [Webhooks](/integrations/webhooks.md#events). * MCP: `list_pending_approvals`, `approve_chore`, `reject_chore`, and `needsApproval`/`approveTimedPlay` on `create_chore` and `update_chore`. ## Kids suggest chores Kids can add their own chores. Maybe piano practice isn't on the chart yet, or they want to help with something new. They send an idea, say how many points they think it's worth, and a grown-up says yes or not this time. **For kids** 1. On **Chores**, tap **💡 Suggest a chore** (**💡 Idea** on a phone). On a wall screen, pick who you are first. 2. Type the chore, pick an emoji, and use **−** and **+** to say how many points you think it's worth. 3. Check what fits: * **Make it repeat**: pick the days (picked ones fill in), and if you like a start time and how long it takes ("20 min" for practicing). Tapping the chore later starts that timer. * **I already did it today**: a grown-up checks it, then the points count. * Neither: it's a one-time chore. Pick **Today**, **Tomorrow** or **Pick a day**. 4. Tap **Send to a grown-up** (until you've typed your idea it says **Type your idea first.** under the button). Your idea shows under **Chore ideas** as **Waiting for a grown-up**, with its days ("Every Thu"). It isn't a chore yet, so it doesn't count and you can't tick it. Changed your mind? **Take back** removes it while it's still waiting. When a grown-up answers, your device gets a notification and **Chore ideas** shows it: "Sam said yes! Piano practice · 4 points" with their note, or "Not this time" with their reason. Tap **Got it** to put it away. A "Not this time" shows only on your own device, never on a shared wall screen. **For parents** * New ideas wait in **To approve** at the top of Chores, counted in the **Chores** badge, and parent devices get a notification ("Maya suggests a chore: Piano practice"). * **Say yes…** shows what they asked for. Keep their points or change them, change the days, start time or timer, add a note, and tap **Approve**. Quick notes like **Great idea!** or **Love the initiative!** fill in with one tap (**Proud of you for practicing!** for an idea with a timer, **Thanks for helping out!** otherwise). Approving makes a normal chore for that kid. If they said they already did it, it's marked done today and they get the points now, once. * **Not this time** sends your note (optional) to the kid instead, with one-tap kind ones such as **Let's do it on Saturday.** * The kid sees your name when you answer from a device that's yours (**Settings → General → This device**, "Whose device is this?"). Otherwise it says "A grown-up". * Turn it off with **Kids can suggest chores** in **Settings → Family** (chore settings). It's on by default, like Rewards. Ideas already waiting can still be answered. * A person can have up to 10 ideas waiting at once. **API and MCP** * `GET /api/chore-suggestions?memberId=` lists ideas that are waiting and answers not yet put away. `POST /api/chore-suggestions {memberId?, title, emoji?, points (0-100), dueDate?, done?, rrule?, dueTime?, timerMinutes?}` sends one. A kid's own device sends and reads only its own. A wall screen has to name `memberId`. `POST /api/chore-suggestions/{id}/seen` puts an answer away, and `DELETE /api/chore-suggestions/{id}` takes back one still waiting (its person's own device, a wall screen or a parent's). * Parent devices only: `POST /api/chore-suggestions/{id}/approve {points?, title?, emoji?, rrule?, dueTime?, timerMinutes?, note?}` (returns the suggestion with `choreId` and `pointsGiven`) and `POST /api/chore-suggestions/{id}/decline {note?}`. * Webhooks: `chore.suggestion.changed`, plus `chore.changed` for the new chore and `chore.completed` for an "already did it" one. * MCP: `list_chore_suggestions`, `approve_chore_suggestion`, `reject_chore_suggestion`. ## Chore library Some jobs don't fit a schedule: clean out the car, wash the windows, flip the mattress. The **chore library** keeps them ready to hand out. Open it with **🧰 Library** at the top of the Chores tab (parent devices only). * Each saved chore has a title, emoji, points, and optionally a checklist, the person it usually goes to, notes, whether it needs a parent's OK, and **About every** a number of days, weeks or months. * **About every** is not a schedule. It's a hint: once a chore has been about that long since it was last done (90% of the way there), it moves to the top with **⏰ Due-ish**. Each row says how it's going, for example "Last done 5 weeks ago · usually every 4 weeks", "Not done yet" or "To do: Maya, Sat". * **Tap a chore** to hand it out: pick **Who** (or **Anyone**) and **When** (**Today**, **Tomorrow**, **This weekend** or **Pick a date**), then **Add chore**. It becomes a normal one-off chore with the same points, checklist and approval setting. The library stays open, so you can hand out a few in a row. * **Again · Maya** gives a chore to whoever got it last time (Maya here), for today, in one tap. **Undo** on the "Added" message takes it back. The rows stay where they are until you close the library, so the next **Again** doesn't move under your finger. * **More… → Make it repeat…** opens the chore editor filled in, repeating at the chore's **About every** (for example every 4 weeks). Change the schedule there if you like. * **More… → Edit library chore…** changes the saved chore (chores already handed out stay as they are), and **Remove from library…** at the bottom of that sheet deletes it. * **Save to library** (in a chore's edit sheet, under **More…**) saves an existing chore to the library. Its history comes along, so "last done" is right from the start. * **New library chore** adds one from scratch. A new family starts with a few common ones (clean out the car, wash the windows, deep-clean the fridge, flip the mattress, organize the garage, wipe the baseboards, rake leaves, sort out the closet). Remove the ones you don't need; they don't come back. "Last done" counts chores made from the library item and approved, so a tick still waiting for a parent's OK doesn't count yet. Wall screens and kids' devices can't open or change the library, but they do the chores handed out from it as usual. The library is included in [export and import](/your-data/export-import.md). ## Points, late completion credit Points are fixed at the moment you tick a chore off. Changing a chore's points later doesn't rewrite history. * Completed **on its day, or early**: full points. * Completed **for a past day**: `lateCompletionCredit` percent of the points, rounded. The default is **50%** (0–100). * Re-ticking an existing completion (for example, to change who did it) keeps the points it already earned. If the re-tick comes from a wall screen or kid's device and names someone else whose ticks need a [parent's OK](#parent-approval), it waits for that OK and earns nothing until then. * A chore can only be ticked for a day it's due on, and not while it's paused. A one-off chore with no day set (made through the API) can be ticked once, for any day. * Wall screens and kids' devices can tick a chore for the last 7 days, today, and one day ahead. Older days are for a parent's device. * A chore waiting for a [parent's OK](#parent-approval) earns its points when it's approved, judged by when it was ticked. ## Streaks and grace days A member's 🔥 streak counts consecutive days on which **every chore assigned to them and due that day** was completed. * Days with nothing due are skipped. They don't break the streak. * Today only counts once its chores are done. * `streakGraceDays` (0–3, default **1**): a streak survives that many missed days in any rolling 7 days. Set it to 0 for the strict rule, where any miss ends the streak. * Streaks look back at most 60 days. 🔥*N* shows from 2 days up. ## Leaderboard Above the columns, a leaderboard ranks members by points, each shown with "pts". The menu at its start picks the period: **Today**, **This week** or **This month**. It changes only the leaderboard, not the chores below. The period is remembered per device, and the week follows the household week start. Tap someone's pill to open their [profile](/using-kinwall/profiles.md). * Ranking is by points, then completions, then name. Members with equal points and completions share a rank. Someone with no points yet shows no rank, so a fresh day doesn't put everyone at #1. * The leader gets 👑 (bouncing when the lead changes). Members with no activity still appear. * `leaderboardEnabled` (default on): turn it off for families that prefer no competition. Apps then hide the leaderboard and rank badges. The API still answers. ## Points to spend Points are also a currency. A member's **balance** is every point they've ever earned from chores, check-ins and [bonus points](#bonus-points), minus what they've spent in the [sticker shop](/using-kinwall/nooks/activities.md#sticker-book) and on [rewards](/using-kinwall/rewards.md). A reward a parent says no to gives its points back. * The leaderboard and the member's today/week points always count what was **earned**. Spending never lowers a rank. * Each leaderboard pill also shows the balance, such as "22 to spend", and so does each person's column ("⭐ 22 to spend"). Tap the column's balance, or **🎁 Rewards** next to the date, to open [Rewards](/using-kinwall/rewards.md) for that person. * Spending is recorded in a points ledger. **Points history** on [Rewards](/using-kinwall/rewards.md#whats-on-the-screen), under the balance, shows it. `GET /api/members/{id}/points` returns `{ balance, earnedTotal, spentTotal, entries }`, with the last 50 ledger entries. The member list (`GET /api/members`) includes `balance` too. * Unticking a completed chore takes its points back out of the balance (deleting a chore doesn't: its history stays). A balance can end up below zero that way. New purchases then wait until it's back up. * **Settings → Family → Chores** has **Rewards** (on/off), **Sticker shop** (on/off) and **Sticker prices** (Free, 50%, 100% or 150%). * `rewardsEnabled` (default on): turn it off and kids spend points only in the sticker shop. Apps hide [Rewards](/using-kinwall/rewards.md), reward goals and the balance links to them. Rewards and past requests are kept. ## Bonus points Sometimes a kid earns points for something that isn't a chore: carrying the groceries, helping a sibling. A parent can give them directly. * On a parent's device, tap **⭐ Give points** next to the date on the Chores tab, or **Give points** under someone's points on their [profile](/using-kinwall/profiles.md). Pick who, how many (+5, +10, +25 or any whole number up to 500), an optional note ("Helped carry groceries", up to 80 characters) and the day it counts on (today or earlier). * Bonus points count like chore points: the balance to spend, today's and this week's points, the [leaderboard](#leaderboard) and the profile's points earned. They aren't a chore, so they don't change [streaks](#streaks-and-grace-days) or the number of chores done. * The kid's own devices get a notification ("🎉 You got 10 bonus points") with the note. * Gave it by mistake? Tap **Undo** on the "Gave Maya 10 points" message, or tap the bonus under **Bonus points** on their profile to take it back. * Only parents' devices can give or take back bonus points. Wall screens and kids' devices see them on the profile but can't add any. With **Chores & points** turned off, there are no bonus points either. * Bonus points only add. To take points away, take back a bonus or untick a chore. ## Setting these options `lateCompletionCredit`, `streakGraceDays`, `leaderboardEnabled`, `rewardsEnabled`, `kidChoreSuggestions`, `stickersEnabled` and `stickerPriceScale` are household settings. Change them with `PATCH /api/settings`: ```bash curl -X PATCH https://kinwall.example/api/settings -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" -d '{"lateCompletionCredit":100,"streakGraceDays":0,"leaderboardEnabled":false}' ``` They're included in [export and import](/your-data/export-import.md). ## Notifications A per-device **Chore reminder** at a set time lists chores still open today for the members that device follows. See [Notifications](/using-kinwall/notifications.md). ## API and MCP * `GET /api/chores/day?date=YYYY-MM-DD`, `POST /api/chores/{id}/complete {date, memberId?}`, `DELETE /api/chores/{id}/complete?date=` * `GET /api/chores/pending`, `POST /api/chores/{id}/approve {date}`, `POST /api/chores/{id}/reject {date, note?}` (parent devices) * `GET/POST /api/chore-suggestions`, `POST /api/chore-suggestions/{id}/seen`, `DELETE /api/chore-suggestions/{id}`; `POST /api/chore-suggestions/{id}/approve|decline` (parent devices). See [Kids suggest chores](#kids-suggest-chores) * `GET /api/leaderboard?period=today|week|month` * `GET /api/members/{id}/points` * `POST /api/points/awards {memberId, points, note?, date?}`, `GET /api/points/awards?memberId=`, `DELETE /api/points/awards/{id}` ([bonus points](#bonus-points), parent devices) * `GET/POST /api/chore-library`, `PATCH/DELETE /api/chore-library/{id}`, `POST /api/chore-library/{id}/assign {date, memberId?, rrule?}` (parent devices) * MCP: `list_chores`, `create_chore`, `update_chore`, `complete_chore`, `uncomplete_chore`, `list_pending_approvals`, `approve_chore`, `reject_chore`, `list_chore_suggestions`, `approve_chore_suggestion`, `reject_chore_suggestion`, `list_chore_library`, `assign_chore_from_library`, `get_leaderboard`, `get_points`, `award_points`, `delete_point_award` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.kinwall.family/using-kinwall/chores.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.