# Umbra Bookshelf

A WordPress plugin to display and manage books for users in multiple languages:
catalogue, ISBN tracking, series, pen names, retailer links, rating
synchronisation, and newsletter delivery.

Umbra Bookshelf began as three separate plugins — **BD Bookshelf**,
**BD BookShelfHelper** and **BD SimpleEmail** — and is now a single consolidated
plugin. This repository continues the history of the original
[Bookshelf](https://git.mini-eq/umbragit/Bookshelf) repository, which is now
closed and archived.

## Repository layout

| Path | What it is |
|---|---|
| `umbra-bookshelf/` | **The plugin.** Books, library and email modules. Start at [`umbra-bookshelf/readme.txt`](umbra-bookshelf/readme.txt). |
| `theme/` | The `bd-bookshelf` WordPress theme. A separate artifact, deliberately **not** renamed in the consolidation. |
| `archive/pre-umbra-releases/` | Release zips of the three pre-merge plugins. Superseded — do not install. |
| `Old/` | Earlier plugin and theme snapshots, kept for reference. |
| `docs/`, mockups, images, `.docx`/`.zip` specs | Design material carried over from the original repository. |

## Documentation

* [`umbra-bookshelf/spec/SPEC_Umbra_Bookshelf_Plugin.md`](umbra-bookshelf/spec/SPEC_Umbra_Bookshelf_Plugin.md)
  — the authoritative specification: identity, naming rules, architecture,
  module responsibilities, admin menu map, lifecycle.
* [`umbra-bookshelf/docs/ARCHITECTURE.md`](umbra-bookshelf/docs/ARCHITECTURE.md)
  — why the plugin is shaped this way.
* [`umbra-bookshelf/docs/KNOWN-ISSUES.md`](umbra-bookshelf/docs/KNOWN-ISSUES.md)
  — defects carried over from the merge, including one deliberately deferred.
* [`umbra-bookshelf/spec/archive/`](umbra-bookshelf/spec/archive/) — pre-merge
  specifications, retained for provenance only.

## Development

```bash
# static checks: syntax, duplicate classes, unresolved requires and assets,
# leftover old identifiers, preserved storage contracts
python3 umbra-bookshelf/tests/verify_structure.py

# runtime boot against stubbed WordPress (each context needs its own process)
php umbra-bookshelf/tests/smoke_runtime.php front
php umbra-bookshelf/tests/smoke_runtime.php admin
```

## Upgrading from the old plugins

Umbra Bookshelf uses the same database tables, option keys, post meta, cron
hooks and shortcodes as the three plugins it replaces, so existing data carries
over without migration.

Install Umbra Bookshelf, then **deactivate** BD Bookshelf, BD BookShelfHelper
and BD SimpleEmail. Do not delete them — deleting runs their uninstall routines,
which drop your tables and options.

## Status

`v1.1.0` resolves the three problems that blocked the consolidation:

* **`bd_books` and `bd_series` schema conflict** — the catalogue schema is now
  canonical, with a migration that preserves data from installations built on the
  old library schema. Legacy tables are renamed aside, never dropped.
* **Duplicated scraping** — Goodreads only, one implementation, driven by a
  single 12-hour cron.
* **Apache/GPL licence mismatch** — GPL-2.0-or-later throughout, which is what
  WordPress.org requires.

## Licence

GPLv2 or later (GPL-2.0-or-later) — WordPress.org compatible. See [`LICENSE`](LICENSE).