RecoReco/README.md

# RecoReco -- calendar-scheduled recurring cards

Kanboard's built-in recurrence is event-triggered (a card recurs when you move or close it).
RecoReco adds **calendar-triggered** recurrence: a card fires on a date, on its own, via cron --
made for bills, rent, and subscriptions.

A card marked recurring **stays** as a template; on schedule, RecoReco spawns a plain
(non-recurring) copy into a column you choose. The template advances to the next date; the copy
keeps the fired date.

RecoReco is opt-in per card and inert until you mark a card, so it needs no per-board setting. It
leaves native recurrence untouched (the two are mutually exclusive per card).

## The idea

- **The due date is the anchor.** All timing (day, month, weekday, time) is read from the card's
  due date -- there are no separate date inputs. A card without a due date cannot be made recurring.
- **Frequencies:** yearly, monthly by day, monthly by weekday, weekly, daily.
- **Last day of the month:** an explicit checkbox (honored only when the due date is the last day,
  or the last such weekday, of its month).
- **Lead time:** "create the copy N days before the due date", so the card shows up early enough
  to act on; the copy is still due on the real day.

## Scheduling (cron)

The engine runs from the CLI command `recoreco:run`. Add it to cron **four times a day** -- at
05:58, 11:58, 17:58 and 23:58:

```
58 5,11,17,23 * * * cd /path/to/kanboard && php cli recoreco:run >> /var/log/recoreco.log 2>&1
```

(Point the path at your install and run it as the user that owns Kanboard's data.) Each run looks
ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one, and
any occurrence whose time is already past is still caught up. `days before` shifts a copy earlier
within that lead. You can also run it by hand any time: `php cli recoreco:run`.

## Status

Working for **monthly by day** (with the last-day rule), driven by cron. The remaining frequencies
(yearly, weekly, daily, monthly by weekday), the recurrence icons, and the FinanceBuddy
installment hand-off arrive in the following versions.

## Requirements

- Kanboard >= 1.2.0
- cron (to run `recoreco:run`)

## Installation

Copy this folder into your Kanboard installation as `plugins/RecoReco/`. The directory name must be
exactly `RecoReco` (Kanboard derives the plugin namespace from the folder name). No build step and
no database migration. Then add the cron entry above.

## License

AGPL-3.0. See LICENSE.