From 0a75b52d457ad22776a36075facae7612139d10f Mon Sep 17 00:00:00 2001
From: Utku Bilen Demir <84389167+UtkuBilenDemir@users.noreply.github.com>
Date: Wed, 23 Sep 2026 11:03:20 +0200
Subject: [PATCH] Kanzi 0.6.12: readme restructure per request
- README.md: Caution -> Kanzi -> centred please give me money+ button (div align center, #111, 8px, shadow) -> headers # Install / # Use / # Coloured highlights / # Tips / # Detailed Guide / # For developers/ CLI / # Releases / # Support
- Coloured highlights section keeps unique single letters y/o/r/e/g/b/p/m with table, full names, bracket stripped example
- Detailed Guide expands Manager tabs (Summary/Integrated/Conflicts/Mappings/Settings+Highlight colours/Artifacts) with incremental note
- Reduce em dashes, British spelling throughout
- Bump to 0.6.12
---
README.md | 98 ++++++++++++++++++++++++++------------------
plugin/manifest.json | 2 +-
updates.json | 9 ++++
3 files changed, 67 insertions(+), 42 deletions(-)
diff --git a/README.md b/README.md
index e7e7fe2..86c0a8f 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,46 @@
-
> [!CAUTION]
> **This project has been heavily vibecoded.**
# Kanzi — Kindle annotations to Zotero
-Import Kindle `My Clippings.txt` highlights into Zotero as native annotations; directly inside Zotero, no terminal needed. Formerly *Kindle Zotero Importer*.
+Import Kindle `My Clippings.txt` highlights into Zotero as native annotations, directly inside Zotero, no terminal needed. Formerly *Kindle Zotero Importer*.
-[
](https://github.com/sponsors/UtkuBilenDemir)
+
-## Install (30 seconds)
+
please give me money+
-1. Download `kindle-zotero-importer.xpi` from [Releases](../../releases) (latest `0.6.11`, or `0.6.10-beta` for preview).
-2. In Zotero: `Tools → Plugins → gear → Install Plugin From File…` → pick the `.xpi` → restart Zotero.
-3. `Tools → Kanzi…` (or `Kindle Zotero Importer…`) to open the manager.
+
Support the project — thank you
-Works with Zotero 7–10; macOS/Windows/Linux; PDF and EPUB. Colours via bracket: `[o] orange`, `[r] red`, `[e] grey`, `[y]` yellow, etc. — all single letters unique, editable in `Settings → Highlight colours`.
+
-## Use
+# Install
-1. **Choose your file**; click `Choose My Clippings.txt` and pick your *cumulative* `My Clippings.txt` from Kindle (`/Documents/My Clippings.txt`); keep the window open; you will see live progress.
-2. **Check Integrated**; after the run, `Integrated` shows what was imported (`Highlight Text`; `Citekey`; `Added On`; `Integrated`; `Page`); filter to find anything.
-3. **Fix Conflicts**; if a Kindle title did not match a Zotero item, `Conflicts` shows it with up to 3 suggestions `citekey · title (score%)`; click `Use` on the right one; or type any `citation key` / `Zotero key` / `Item ID` under `Use Custom`; or `Ignore Title` to skip it forever; if you map `chabot2013` for one `Simondon` variant, it will offer to apply the same mapping to the other variants with that candidate.
-4. **Re-import**; after you have fixed one or more titles, click `↻ Re-import with saved overrides` (re-uses the last file; or asks for it); only new/changed highlights are re-positioned; already integrated ones are skipped, so the second run is fast; check `Full re-import from scratch` only if you want to rebuild everything.
-5. **Mappings**; see all titles you have approved or ignored, newest first, with date; `Delete` any entry to send it back to `Conflicts` for re-matching.
-6. **Settings / Artifacts**; change `Python`/`Zotero DB` paths and `Save Settings`; or `Open`/`Reveal` any generated file (`mismatch-review.md`; `match-overrides.json`; …).
+**30 seconds, no terminal:**
-Your choices are saved in `match-overrides.json` in the project folder; back it up, share it, or delete an entry to undo a mapping.
+1. Download `kindle-zotero-importer.xpi` from [Releases](../../releases) (latest `0.6.12`, or `0.6.11-beta` for preview).
+2. In Zotero: `Tools` → `Plugins` → `gear` → `Install Plugin From File…` → pick the `.xpi` → restart Zotero.
+3. `Tools` → `Kanzi…` to open the manager.
-## Highlight colours
+Works with Zotero 7 to 10, macOS, Windows and Linux, PDF and EPUB.
-Start a highlight **or** its Kindle note with `[code]` to set colour — the bracket is stripped, so Zotero shows only the text.
+# Use
+
+1. **Choose your file.** Click `Choose My Clippings.txt` and pick your *cumulative* `My Clippings.txt` from Kindle (`Documents/My Clippings.txt`). Keep the window open. You will see live progress.
+2. **Check Integrated.** After the run, `Integrated` shows what was imported. Columns are `Highlight Text`, `Citekey`, `Added On`, `Integrated` and `Page`. Use the filter to find anything.
+3. **Fix Conflicts.** If a Kindle title did not match a Zotero item, `Conflicts` shows it with up to three suggestions `citekey · title (score%)`. Click `Use` on the right one. Or type any citation key, Zotero key or item ID under `Use Custom`. Or `Ignore Title` to skip it forever. If you map `chabot2013` for one `Simondon` variant, it will offer to apply the same mapping to the other variants with that candidate.
+4. **Re-import.** After you have fixed one or more titles, click `Re-import with saved overrides`. It reuses the last file, or asks for it. Only new or changed highlights are repositioned. Already integrated ones are skipped, so the second run is fast. Tick `Full re-import from scratch` only if you want to rebuild everything.
+5. **Mappings.** See all titles you have approved or ignored, newest first, with date. Use `Delete` to send any entry back to `Conflicts` for rematching.
+6. **Settings and Artifacts.** Change `Python` or `Zotero DB` paths and `Save Settings`. Or use `Open` or `Reveal` for any generated file, such as `mismatch-review.md` or `match-overrides.json`.
+
+Your choices are saved in `match-overrides.json` in the project folder. Back it up, share it, or delete an entry to undo a mapping.
+
+# Coloured highlights
+
+You can specify the colour of your highlights while writing the note by adding a bracket at the start.
+
+Write `[o] This is orange` on Kindle, either as the highlight itself or as the note attached to it. Kanzi strips the bracket and imports the highlight in that colour. For example, `[o] This is orange` becomes orange highlight with text `This is orange`. If the note is `[r] important`, the highlight turns red and the note becomes `important`.
+
+All codes are single letters and unique:
| Code | Full name | Hex | Colour |
|------|-----------|-----|--------|
@@ -42,44 +53,49 @@ Start a highlight **or** its Kindle note with `[code]` to set colour — the bra
| `p` | `purple` | `#a28ae5` | purple |
| `m` | `magenta` / `pink` | `#e56eee` | magenta |
-All single letters are unique (`e` is grey to keep `g` for green). Both `[o]` and `[orange]` work, case-insensitive, whitespace trimmed. Example: Kindle highlight ` [o] This is orange` → orange highlight with text `This is orange`; Kindle note `[r] important` attached to a highlight → that highlight turns red, note becomes `important`. Change any mapping in `Settings → Highlight colours` (hex picker + preview, `+ Add mapping`, `Reset to defaults`) — British spelling throughout.
+Both `[o]` and `[orange]` work, case is not sensitive, and space after the bracket is ignored. Change any mapping in `Settings` → `Highlight colours` using the hex picker and preview. Use `+ Add mapping` or `Reset to defaults`. British spelling is used throughout.
-## Manager — User guide
+# Tips
-`Tools → Kanzi…` opens the manager (`chrome://kanzi/content/manager.html`, Zotero 7–10).
+* Keep `My Clippings.txt` cumulative. Do not clear it on the Kindle. The importer remembers what is already integrated via `kindle-id:` tags, so re-imports are incremental.
+* If a highlight is in the wrong place, check that the Zotero item has the correct PDF or EPUB attached, not a link. `Matched-title-no-attachment` in `Conflicts` means that.
+* `Full re-import` is only needed if you changed many mappings at once or want to rebuild from scratch.
+* Past highlights will recolour incrementally when you add a bracket code to them, or when you change the colour map in Settings. Otherwise use `Full re-import` to recolour everything.
-* **Summary** — `clippings` / `unique titles` / `final annotations` / `conflicts`; `Match Statuses` (`matched`/`ignored`/`unmatched`/`ambiguous`) and `Plan Statuses` (`positioned`/`epub-text-not-found` etc.). Run panel shows `Choose My Clippings.txt`, `progress` + `stage`/`detail`, `Full re-import` checkbox.
-* **Integrated** — last `import-plan.final.json` annotations (`Kindle Title` | `Citekey` | `Highlight Text` | `Added On` | `Integrated` | `Page` with colour swatch). Filter top-right, `400` shown, sortable/resizable.
-* **Conflicts** — unresolved titles (`Title match` / `Override suggestion` / `Attachment/position`). `Candidates / Detail` shows `N suggestion(s) — top: citekey (score%)`, each candidate has `Use` button, plus `Use Custom` (`citekey` / `Zotero key` / `ID`) and `Ignore Title`. Saving shows `Re-import` bar (`↻ Re-import with saved overrides` re-uses last file). Title-variant grouping: if you `Use` `chabot2013` for one `Simondon` variant, it offers to apply to other variants with same candidate.
-* **Mappings** — persistent `match-overrides.json` (`Kindle Title` | `Resolution` | `Status` | `Count` | `Updated` | `Delete`). `Delete` sends it back to `Conflicts`. Filterable.
-* **Settings** — `Project directory`, `Python`, `Zotero DB`, `Zotero storage`, `Share anonymized annotations` (on by default, `annotation.utkubilen.de`, private, hashed only), **Highlight colours** table as above. `Save Settings` writes `plugin-config.json` + `colour-map.json` for the pipeline (`src/kindle_zotero_importer/cli.py:12` `_load_colour_map()`), no restart. Also `Artifacts` helpers.
-* **Artifacts** — `Mismatch review` (`docs/mismatch-review.md`), `Persistent overrides`, `Generated suggestions`, `Positioned plan`, `Final writer plan`, `Plugin summary` — each `Open`/`Reveal`.
+# Detailed Guide
-Incremental is default: only new/changed highlights + colour-changed past highlights are re-positioned; use `Full re-import` to rebuild all (e.g. after changing many mappings).
+`Tools` → `Kanzi…` opens the manager.
-## Tips
+**Summary.** Shows `clippings`, `unique titles`, `final annotations` and `conflicts`. Also `Match Statuses` and `Plan Statuses`. The run panel shows `Choose My Clippings.txt`, progress, stage and detail, and the `Full re-import` checkbox.
-- Keep `My Clippings.txt` cumulative (do not clear it on the Kindle); the importer remembers what is already integrated via `kindle-id:` tags, so re-imports are incremental.
-- If a highlight is positioned in the wrong place, check that the Zotero item has the correct PDF/EPUB attached (not a link); `Matched-title-no-attachment` in `Conflicts` means that.
-- `Full re-import` is only needed if you changed many mappings at once or want to rebuild from scratch.
-- Colours: start a highlight or note with `[o]`, `[r]` red, `[e]` grey, `[y]` yellow, `[g]` green, `[b]` blue, `[p]` purple, `[m]` magenta — e.g. `[o] This is orange` → orange, bracket stripped. Full names (`[orange]`, `[red]`, `[grey]` etc.) also work. Change mappings in `Settings → Highlight colours` (British spelling).
+**Integrated.** The last `import-plan.final.json` annotations. Columns are `Kindle Title`, `Citekey`, `Highlight Text`, `Added On`, `Integrated` and `Page` with colour swatch. Filter at the top right, 400 shown, sortable and resizable.
-## For developers / CLI
+**Conflicts.** Unresolved titles. Type is `Title match`, `Override suggestion` or `Attachment/position`. `Candidates` shows `N suggestion(s) — top: citekey (score%)`. Each candidate has a `Use` button. Below that is `Use Custom` and `Ignore Title`. Saving shows the `Re-import` bar. If you use `chabot2013` for one Simondon variant, it offers to apply to other variants with the same candidate.
+
+**Mappings.** Persistent `match-overrides.json`. Columns are `Kindle Title`, `Resolution`, `Status`, `Count` and `Updated`. Use `Delete` to send it back to `Conflicts`. Filterable.
+
+**Settings.** `Project directory`, `Python`, `Zotero DB`, `Zotero storage`, `Share anonymized annotations` (on by default, `annotation.utkubilen.de`, private, hashed only), and `Highlight colours` as above. `Save Settings` writes `plugin-config.json` and `colour-map.json` for the pipeline. No restart is needed.
+
+**Artifacts.** `Mismatch review`, `Persistent overrides`, `Generated suggestions`, `Positioned plan`, `Final writer plan` and `Plugin summary`. Each has `Open` and `Reveal`.
+
+Incremental is default. Only new, changed or colour-changed highlights are repositioned.
+
+# For developers / CLI
```sh
python scripts/build_plugin.py # → dist/kindle-zotero-importer.xpi
python -m kindle_zotero_importer run "/path/to/My Clippings.txt" --workdir . --pretty
-python -m kindle_zotero_importer run ... --full # ignore incremental; re-process all
+python -m kindle_zotero_importer run ... --full # ignore incremental and reprocess all
```
-PDF positioning uses Poppler (`pdftotext`; `pdftohtml`; `pdfinfo`) + `qpdf` fallback; EPUB uses CFI. Zotero writes are only via `Zotero.Annotations`; never direct `zotero.sqlite` writes.
+PDF positioning uses Poppler (`pdftotext`, `pdftohtml`, `pdfinfo`) plus `qpdf` fallback. EPUB uses CFI. Zotero writes are only via `Zotero.Annotations`. It never writes `zotero.sqlite` directly.
-Anonymized sharing is **on by default** to help future development (only `citation key`; hashed highlight; `color`; `has comment` + note; `added_on`; `integrated_at`; never raw highlight text); opt out anytime in `Manager → Settings` → uncheck `Share anonymized annotations` (also `annotation.utkubilen.de`, private, no AI).
+# Releases
-## Releases
+Stable releases are on `Releases` with `kindle-zotero-importer.xpi` and `updates.json` attached. Pre-releases (`beta`) are marked `Pre-release` on GitHub. Zotero auto-updates from `releases/latest/download/updates.json`.
-Stable releases are on `Releases` with `kindle-zotero-importer.xpi` + `updates.json` attached. Pre-releases (`beta`) are marked `Pre-release` on GitHub. Zotero auto-updates from `releases/latest/download/updates.json`.
-
-## Support
+# Support
Issues and pull requests welcome at [Issues](../../issues).
+
+Anonymized sharing is on by default to help future development. It sends only citation key, hashed highlight, colour, has comment and note, added on and integrated at. It never sends raw highlight text. Opt out any time in `Manager` → `Settings` → uncheck `Share anonymized annotations` (also `annotation.utkubilen.de`, private, no AI).
diff --git a/plugin/manifest.json b/plugin/manifest.json
index b3b92bd..94ff9f2 100644
--- a/plugin/manifest.json
+++ b/plugin/manifest.json
@@ -1,7 +1,7 @@
{
"manifest_version": 2,
"name": "Kanzi",
- "version": "0.6.11",
+ "version": "0.6.12",
"description": "Kindle annotations to Zotero — My Clippings.txt → native annotations.",
"homepage_url": "https://github.com/UtkuBilenDemir/kindle-zotero_importer",
"author": "Utku Bilen Demir",
diff --git a/updates.json b/updates.json
index dbc6424..ea8b714 100644
--- a/updates.json
+++ b/updates.json
@@ -2,6 +2,15 @@
"addons": {
"kindlezoteroimporter@utkubilen.de": {
"updates": [
+ {
+ "version": "0.6.12",
+ "update_link": "https://github.com/UtkuBilenDemir/kindle-zotero_importer/releases/download/v0.6.12/kindle-zotero-importer.xpi",
+ "applications": {
+ "zotero": {
+ "strict_min_version": "6.999"
+ }
+ }
+ },
{
"version": "0.6.11",
"update_link": "https://github.com/UtkuBilenDemir/kindle-zotero_importer/releases/download/v0.6.11/kindle-zotero-importer.xpi",