QualKard/README.md

# QualKard -- flashcard spaced repetition on your Kanboard

Turn a Kanboard board into a spaced-repetition flashcard deck. Each card is a flashcard --
title is the prompt, description is the answer. You study a card, grade how it went by
dragging it into a grade column, and QualKard schedules when it should come back. Cards you
find easy drift far into the future; hairy ones return tomorrow.

The scheduling math is ported from Ruben's C program **qualcard** (the "K" here just marks the
Kanboard port). The card movement -- bringing a card back when it falls due -- is done by the
companion **RecoReco** plugin, so QualKard needs RecoReco installed and RecoReco's cron running.

QualKard is **opt-in per board**: installing it changes nothing until a project manager sets a
specific board up under Settings -> Integrations. Setting a board up **restructures its
columns**, so it is a deliberate, confirmed action -- see below.

## The study board

Setting a board up gives it exactly seven columns, each with a fixed role:

```
Drafts | Study | Hairy | Hard | Medium | Easy | Done
```

- **Drafts** -- where new and reset cards wait. A draft is inert: it never comes due on its own.
- **Study** -- the review queue. RecoReco moves a card here when it falls due; this column is
  itself the "overdue" backlog, so it can hold more than one day's worth.
- **Hairy / Hard / Medium / Easy** -- the four grade columns. You review a card in Study, then
  drag it into one of these to record how it went.
- **Done** -- a resting place you drag a card to when you want it out of rotation. A card in Done
  does not come back (it is the one column that does not re-trigger).

## Studying

1. Read the prompt (the card title) in **Study**, recall the answer, then open the card to check
   the description.
2. Drag the card into the grade column that matches how it went:

   | Column | Meaning | Score |
   |--------|---------|------:|
   | Hairy  | no idea / wrong        | 0.0 |
   | Hard   | right, but a struggle  | 1.3 |
   | Medium | right, some effort     | 3.0 |
   | Easy   | instant                | 5.0 |

3. QualKard folds that score into the card's running average and sets the card's **due date** the
   right number of days out (1 day for a hairy average, up to 11 for a mastered one). RecoReco
   picks the card up from the grade column and, when it next falls due, moves it back to **Study**.

You never edit a due date or move a card back yourself -- grading is the only action.

### How the schedule is computed

Each card keeps a running average of its scores. A brand-new card is seeded a little below its
first score; after that the average is the mean of the old average and the new score. The average
maps to an interval:

| Average    | Interval |
|------------|---------:|
| <= 0.60    | 1 day    |
| <= 1.35    | 2 days   |
| <= 2.20    | 3 days   |
| <= 3.05    | 5 days   |
| <= 3.90    | 7 days   |
| <= 4.92    | 9 days   |
| otherwise  | 11 days  |

So a card you keep grading Easy climbs toward an 11-day gap, while one you keep missing stays at a
day or two until it sticks.

## The mastery badge

Each card shows a small badge under its title, on the board and at the top of the opened card:

- **new** (yellow) -- an unread card that has never been graded.
- a **percent** of mastery (the average as a fraction of 5), coloured **red** below 50%,
  **green** through 89%, and **blue** at 90% and up.

## Requirements

- Kanboard >= 1.2.0
- The **RecoReco** plugin, installed and enabled, with its cron task running (RecoReco is what
  moves due cards back to Study). QualKard's setup button stays disabled until RecoReco is present.

QualKard refuses to set up a board that has **FinanceBuddy** enabled: the restructure would wreck a
finance board's columns. Disable FinanceBuddy on that board first, or use a different board.

## Installation

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

Then, on the board you want to study:

1. Go to Settings -> Integrations.
2. Under QualKard, click **Set up QualKard study board**, and confirm. This renames the board's
   columns to the seven roles above (creating or removing columns to reach exactly seven) and moves
   every existing card into Drafts.
3. Make sure RecoReco's cron is running so due cards come back.

From the same page you can later **Reset all cards** (send every card back to Drafts, unread) or
**Disable QualKard machinery** (stop the automation without touching your columns or cards).

## How it stores data

No database migration. The per-board enable flag and the seven column roles are stored in project
metadata; each card's running average lives in task metadata, and QualKard writes the card's due
date and RecoReco's per-card recurrence config. Uninstalling the plugin leaves that metadata
harmlessly in place -- your columns and cards are untouched.

## License

AGPL-3.0. See LICENSE.

## More Kanboard plugins by Ruben (drbeco)

All free and AGPL-3.0, at [code.beco.cc](https://code.beco.cc/beco):

- **[RecoReco](https://code.beco.cc/beco/RecoReco)** -- calendar-scheduled recurring cards (yearly,
  monthly, weekly, daily), driven by the card due date. QualKard rides RecoReco's move engine to
  bring due flashcards back to the Study column.
- **[FinanceBuddy](https://code.beco.cc/beco/FinanceBuddy)** -- attach a money value to each card,
  show it on the card, and total it per column, so a board can double as a simple finance board.
- **[OrganonTweaks](https://code.beco.cc/beco/OrganonTweaks)** -- an umbrella of small
  quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due
  dates, extra search keywords and shared board filters, and more.
- **[BulkMoveTasks](https://code.beco.cc/beco/BulkMoveTasks)** -- move every task from one board
  column to another in a single action.
- **[ShrinkVertically](https://code.beco.cc/beco/ShrinkVertically)** -- shrink vertically-collapsed
  board columns so the horizontal scrollbar stays within reach.
- **[TweakDrag](https://code.beco.cc/beco/TweakDrag)** -- board drag and touch niceties:
  drag-to-scroll, a wider column gap, and smoother card dragging.