# FlashLearn

FlashLearn is a local Leitner flashcard system with two entry points:

- an MCP stdio server so an AI client can create decks, create cards, read cards, study cards, promote/demote cards, and inspect progress
- a localhost web app for interactive study and deck progress

The app stores data in `data/flashlearn.json` by default. Set `FLASHLEARN_DATA=/path/to/file.json` to use another location.

## Run the Web App

```sh
npm run web
```

Open `http://127.0.0.1:5731`.

If that port is already in use, FlashLearn automatically tries the next port and prints the URL.

The web UI lets you add decks and cards, study due cards, turn on `All cards` to study beyond the due queue, reveal answers, skip cards, mark cards as remembered or forgotten, manually promote/demote cards, search cards, and view progress by deck and Leitner box.

The dashboard also shows an annual practice heatmap with daily average, days learned, longest streak, and current streak; category/tag progress chips; and active toggles for due cards, mastered cards, empty decks, archived decks, and practice-focus mode. Category selection filters both the card library and the study queue, and each card in the library has `Practice`, `Edit`, promote/demote, and delete actions for immediate recall and cleanup.

Use `Backup JSON` to download a full `flashlearn-backup.json`, or `Export CSV` to download card rows for spreadsheet review. Deck settings support renaming, descriptions, custom Leitner intervals such as `0,1,3,7,14`, archive/restore, and delete.

Keyboard shortcuts while not typing in a form:

- `r` or `Space`: reveal
- `1` or `f`: forgot
- `2` or `k`: remember
- `s`: skip
- `p`: promote
- `d`: demote

The card library can filter by box, due date range, mastery state, minimum review count, and maximum review count.

## Run the MCP Server

```sh
npm run mcp
```

Example MCP client config for Codex or another JSON-configured MCP client:

First, get the repository's absolute path from its root:

```sh
pwd -P
```

Replace `/absolute/path/to/flashlearn` below with that output. This keeps the
configuration portable between clones and does not depend on a particular user
account or Desktop layout.

```json
{
  "mcpServers": {
    "flashlearn": {
      "command": "node",
      "args": ["/absolute/path/to/flashlearn/src/mcp-server.js"]
    }
  }
}
```

Example Claude Desktop config:

```json
{
  "mcpServers": {
    "flashlearn": {
      "command": "node",
      "args": ["/absolute/path/to/flashlearn/src/mcp-server.js"],
      "env": {
        "FLASHLEARN_DATA": "/absolute/path/to/flashlearn/data/flashlearn.json"
      }
    }
  }
}
```

Available MCP tools:

- `create_deck`
- `list_decks`
- `update_deck`
- `archive_deck`
- `delete_deck`
- `create_card`
- `update_card`
- `delete_card`
- `read_cards`
- `due_cards`
- `review_card`
- `promote_card`
- `demote_card`
- `progress`
- `export_data`

Useful MCP tool arguments:

- `create_deck` and `update_deck`: pass `boxIntervalsDays` for deck-specific Leitner spacing.
- `list_decks`, `read_cards`, `due_cards`, and `progress`: pass `includeArchived` to include archived decks.
- `read_cards`: filter with `query`, `tag`, `dueOnly`, `dueBefore`, `dueAfter`, `box`, `mastered`, `reviewCountMin`, `reviewCountMax`, and `hideMastered`.
- `export_data`: pass `format: "json"` for backup data or `format: "csv"` for card rows.

## Leitner Behavior

New cards start in box 1 and are due immediately. The default box intervals are:

```txt
box 1: now
box 2: 1 day
box 3: 2 days
box 4: 4 days
box 5: 7 days
box 6: 14 days
box 7: 30 days
```

When you remember a card, FlashLearn promotes it one box. When you forget a card, it returns to box 1. The highest box counts as mastered, but the card can still be studied manually or demoted later.

## Verification

Install the locked dependencies and Chromium once in a fresh clone:

```sh
npm ci
npx playwright install chromium
```

Then run the complete verification suite:

```sh
npm test
npm run smoke:mcp
npm run smoke:web
npm run test:ui
```

`npm run test:ui` runs Playwright against an isolated temp data file and writes desktop/mobile screenshots under `test-results/`.

GitHub Actions runs the same four gates on Node.js 22. The CI runner also
installs Chromium and its Linux system dependencies before the UI tests.

## License

FlashLearn is available under the [MIT License](LICENSE). The npm package
remains marked `private` to prevent accidental publication.

## Research Note

See [docs/card-systems-research.md](docs/card-systems-research.md) for researched alternatives and why this project uses Leitner as the default scheduler.