# Project pack: Kavita @ d549d5b

Facts about **Kavita** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Kavita is a self-hosted library and web reader for comics, manga, light novels and e-books. It scans your folders, builds a library with covers and series information, tracks reading progress and offers a reader that works well on phones and tablets. It supports multiple users with age ratings.

## Version and source
- Repository: https://github.com/Kareadita/Kavita
- Pinned commit: `d549d5b1609086c8190b9bee6eb48ebfed71e1df`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/Kareadita/Kavita/archive/d549d5b1609086c8190b9bee6eb48ebfed71e1df.zip
- Official docs: https://wiki.kavitareader.com
- Live demo: https://www.kavitareader.com/#demo. See the project site for the demo and its sign-in.
- Licence: **GPL-3.0-only**. Free to use and change. If you share your changed version with other people (give them the code or app), you must share your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/Kareadita/Kavita bespoke-kavita
  cd bespoke-kavita
  git checkout --detach d549d5b1609086c8190b9bee6eb48ebfed71e1df
  # Prepare development requirements and local configuration first.
  dotnet restore
  cd UI/Web
  npm install
  npm start
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name kavita -p 5000:5000 -v /path/to/your/books:/books -v kavita-config:/kavita/config jvmilazz0/kavita:latest
  # then open http://localhost:5000 and create the admin account
  ```

- Needs: Docker for a trial, .NET SDK and Node for development
- Develop: `dotnet run --project Kavita.Server  # and, in another terminal: cd UI/Web && npm start`
- Test: `dotnet test`
- Stack: csharp, typescript (ASP.NET Core, Angular, Entity Framework, SQLite). Difficulty for a non-developer with an AI: **advanced**. A large .NET back end and an Angular front end. Libraries, users and reader settings need no code; changes to the reader or scanner are real engineering.

## Customisation points (settings → extend → code)
- **libraries-and-users** [settings]: Which folders are libraries and who can read what. → `Admin → Libraries, Users and age restrictions`
- **reader-settings** [settings]: Reading direction, fit, colour and fonts. → `In the reader, under Settings`
- **opds** [extend]: Read from other apps on your phone or e-reader. → `Admin → Settings → OPDS`
- **angular-ui** [code]: Screens and the reader. → `UI/Web/src`
- **server-services** [code]: Scanning, metadata and API. → `Kavita.Services and Kavita.Server`

## Must keep working
- EF Core migrations. Add new ones; never edit old ones.
- Age restriction and library permission checks.
- The scanner and file handling, so your files are never altered.

## Staying updatable
Use libraries, themes and OPDS. For code changes, keep changes in the Angular app or in new services.

## Data, costs and safety
- Personal data: **yes**. Stored in: A SQLite database and covers in /kavita/config; your books stay in your own folders. Back up the config folder. Your library files are not modified.
- Service: Metadata providers (optional) (optional, free): Better series and cover data.
- Setting `TZ`: Your time zone so scans and schedules run at the right time.
- Don't expose it directly to the internet without HTTPS and strong passwords.
- Respect copyright. Use it for books you own.

---

# Customising Kavita

Kavita is a .NET back end with an Angular front end. Most households only need library settings and themes.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Angular app | UI/Web/src/ |
| API controllers | Kavita.Server/ |
| Services (scanner, metadata) | Kavita.Services/ |
| Database and migrations | Kavita.Database/ |
| Models | Kavita.Models/ |
| Tests | the Kavita.*.Tests projects |

## Use the gentlest change first

1. **Settings (no code):** libraries, users, age ratings and reader preferences.
2. **Extend:** OPDS and the API.
3. **Code:** UI components and services.

## Recipes

- **New reader theme:** add a theme in the Angular styles and register it in the reader settings.
- **New stats card:** add an endpoint in Kavita.Server and a component in the dashboard.

## Running and checking your changes

- `dotnet test` for the projects you changed.
- Scan a small folder of sample books and open one in the reader.

## Pitfalls

- Use a copy of your library folders while developing.
- Add migrations for database changes.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/kavita/d549d5b/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/kavita/d549d5b/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/kavita/d549d5b/r2/SKILL.md)