docs(v0.20): pre-release hygiene - smoke spec, help, API, lessons, coverage

Pre-release sweep per release-workflow.md Step 11 + ai-workflow.md
"Order for new features" step 7 (smoke spec required for every
new UI feature).

- e2e/smoke/ai-review.spec.ts: 4 Playwright smoke tests for the
  AI Review UI surface (three radio focus buttons render, non-prose
  warning toggles per chapter type, mocked happy-path download-report
  link). Uses route mocks to avoid requiring a live LLM backend.
- docs/help/{de,en}/ai.md: rewrote Chapter Review section with the
  three focus modes (Style / Consistency / Beta Reader), cost
  estimate, non-prose warning, persistence + download, async
  progress. Mirrors the actual v0.20 UI.
- docs/API.md: documents the 8 new /api/ai/ endpoints including the
  async flow, SSE stream, FileResponse download, cost estimate, and
  UI metadata endpoint.
- .claude/rules/lessons-learned.md: new AI Review extension section
  with 7 pitfalls discovered during the release window (backup-import
  soft-delete dedup, manuscripta output/ cleanup between format
  runs, Pandoc multi-doc YAML, CSS specificity trap h2+p vs
  p:not(:first-child), TipTap useEditor not flushing editor.storage,
  prefix testid overmatch, recovery draft contentHash contract).
- docs/audits/current-coverage.md: v0.20.0 addendum with the +181
  test delta (1,271 -> 1,452 total automated tests).

Author: astrapisixtynine

.claude/rules/lessons-learned.md

@@ -395,3 +395,49 @@ Stability filter:
 
 - `vite-plugin-pwa@1.2.0` (latest as of 2026-04-18) lists Vite `^3 || ^4 || ^5 || ^6 || ^7` in its peer deps. No Vite 8 support yet. Attempting Vite 6 -> 8 with PWA installed will either refuse to install or runtime-break.
 - This is why DEP-04 landed as Vite 6 -> 7, not 6 -> 8. The Vite 8 bump is deferred until vite-plugin-pwa publishes compat. Check `npm view vite-plugin-pwa peerDependencies` before attempting the next bump.
+
+## AI Review extension (v0.20.0)
+
+### Backup import must check soft-delete state before dedup
+
+- `backup_import._restore_book_from_dir` previously treated any pre-existing `Book.id` in the DB as "already imported" and returned False. That check predates the soft-delete / trash feature: a backup made before trashing silently could not be restored once the books had been moved to trash - the importer saw them in the DB (with `deleted_at` set) and refused to rebuild.
+- Fix: when the pre-existing row is soft-deleted, HARD-delete it along with its chapters + assets, then fall through to the fresh-insert path. Do NOT try to revive via per-attribute setattr: the backup JSON does not carry every NOT NULL column (`ai_tokens_used`, `created_at`, `updated_at`), so SQLAlchemy emits an UPDATE that sets those to NULL and the integrity constraint trips. Hard-delete + fresh-insert sidesteps the whole partial-update dance and matches the backup's snapshot semantics.
+- Generalizes: any "idempotent by id" import path added before a soft-delete feature becomes silently buggy. Always branch on `deleted_at IS NULL` when deduping.
+
+### manuscripta `run_export` moves `output/` to `backup/` on every call
+
+- `manuscripta.export.book.run_export` copies the existing `project_dir/output/` to `project_dir/backup/` at the start of every invocation and creates a fresh `output/`. A list of per-format output paths collected across a batch-export loop contains stale paths by the time the loop finishes.
+- Symptom in v0.19.x: `FileNotFoundError` at `zipfile.ZipFile.write(f, f.name)` inside `/api/books/{id}/export/batch`, referencing a file that existed moments earlier.
+- Fix: after each `run_pandoc` call, IMMEDIATELY copy the produced file into a stable staging directory (`tmp_dir/batch/`) and zip from there. Do NOT keep references to files under `project_dir/output/` across subsequent `run_export` calls.
+
+### Pandoc-wrapped metadata.yaml is a multi-doc YAML stream
+
+- The project exporter wraps `metadata.yaml` in Pandoc-style `---` / `---` document markers. PyYAML's `safe_load` expects exactly one document and raises `yaml.composer.ComposerError` on any trailing `---` (even if the second document is empty).
+- Fix: use `yaml.safe_load_all(f)` and return the first non-empty document. Handles both the bare and the Pandoc-wrapped shapes in one code path.
+- Regression: `smart_import` crashing with 500 on a ZIP that `/api/backup/export` had just produced.
+
+### CSS specificity trap: `h2 + p` loses to `p:not(:first-child)`
+
+- Specificity for `[data-app-theme="classic"] .ProseMirror h2 + p`: (0, 1, 1, 2) - 1 attr, 1 class, 2 elements.
+- For `[data-app-theme="classic"] .ProseMirror p:not(:first-child)`: (0, 1, 2, 1) - 1 attr, 1 class + 1 pseudo-class = 2 "classes", 1 element. The pseudo-class pushes the base rule ahead of the adjacent-sibling override.
+- When both rules match (a paragraph that directly follows a heading AND is not the first child), the higher-specificity `:not(:first-child)` wins and the heading override never applies.
+- Fix: append `:not(:first-child)` to each `h* + p` override. Combined (0, 1, 2, 2) beats the base (0, 1, 2, 1).
+- Generalizes: any CSS override against a `:not(:first-child)` base rule needs at least the same pseudo-class weight.
+
+### TipTap `useEditor` does NOT flush `editor.storage` reads to React
+
+- A status-bar word count written as `{editor?.storage.characterCount?.words()}` inline in JSX looks fine but does not update reliably after keyboard input. TipTap's built-in re-render on transaction fires for selection changes but not for every content transaction we rely on.
+- Reliable fix: subscribe explicitly via `editor.on('update', () => forceUpdate())`, or mirror the count into React state via `useState` + `editor.on('update')`.
+- Surfaced as a smoke-test failure in `smoke/editor-formatting.spec.ts` "word count updates after typing". Currently skipped with a reference to issue #9 until the subscribe pattern is wired up.
+
+### Prefix testid selectors match every nested testid that shares the prefix
+
+- A selector like `[data-testid^='book-card-']` cleanly matches each card root AND every nested child testid that shares the prefix (`book-card-menu-{id}`, `book-card-menu-delete-{id}`). `toHaveCount(N)` returns `2N` or more per visible card.
+- Fix: `[data-testid^='book-card-']:not([data-testid*='-menu-'])`, or give the root a distinct testid like `book-card-root-{id}`.
+- Same shape as the `[class^=""]` overmatch antipattern. Always test a prefix selector against the full rendered surface before shipping.
+
+### IndexedDB recovery draft `contentHash` is a MATCH check, not a MISMATCH
+
+- `frontend/src/db/drafts.ts#checkForRecovery` returns a draft iff `draft.contentHash === hashContent(serverContent)` AND `draft.content !== serverContent`. The contract is "this draft was written against THIS server state, local content is newer". Seeding a test draft with `contentHash: '_mismatch_'` will NOT trigger the recovery banner.
+- A misleading test comment saying "must differ from server hash" burned multiple sessions before the `checkForRecovery` source was re-read.
+- When writing tests that seed IndexedDB, compute the hash of the real server content inside the seed script rather than using a sentinel value.

docs/API.md

@@ -32,6 +32,7 @@ Groups under `backend/app/routers/` (router prefix in parentheses):
 | `licenses`          | `/api/licenses`                                 | License activation and management                    |
 | `settings`          | `/api/settings`                                 | App settings, plugin settings, theme                  |
 | `plugin_install`    | `/api/plugins`                                  | Plugin ZIP installation, discovery, health            |
+| `ai`                | `/api/ai`                                       | Core AI: chat, generate, review (sync + async), marketing text, providers |
 
 Example endpoints (not exhaustive):
 
@@ -46,6 +47,23 @@ Example endpoints (not exhaustive):
 - `GET /api/export/jobs/{id}/stream` - Server-Sent Events progress feed
 - `POST /api/books/{id}/audiobook/dry-run` - sample preview + cost preview
 
+### AI review extension (v0.20.0)
+
+The `/api/ai/` router hosts the multi-provider AI features. The review path supports both synchronous (legacy) and async flows:
+
+- `POST /api/ai/review` - synchronous chapter review; accepts `chapter_type` so the system prompt can tailor feedback per section (e.g. dedication vs chapter).
+- `POST /api/ai/review/async` - submit a review as a background job. Returns `{job_id, review_id}`. The worker persists a Markdown report to `uploads/{book_id}/reviews/{review_id}-{chapter-slug}-{YYYY-MM-DD}.md`.
+- `GET /api/ai/jobs/{job_id}` - poll current status, progress and (when terminal) the inline review.
+- `GET /api/ai/jobs/{job_id}/stream` - Server-Sent Events feed of progress events (`review_start`, `review_llm_call`, `review_done`, `stream_end`).
+- `DELETE /api/ai/jobs/{job_id}` - cancel a running review.
+- `GET /api/ai/review/{review_id}/report.md?book_id=...` - download the persisted Markdown report.
+- `POST /api/ai/review/estimate` - rough input-token + USD cost estimate (uses a chars/4 heuristic and a small per-model pricing dict).
+- `GET /api/ai/review/meta` - UI metadata: all focus values, the three primary UI focus values, non-prose chapter types, supported languages, chapter types. The frontend reads this to drive the radio buttons + non-prose warning without hardcoding.
+
+Review focus values: `style` (existing) plus `consistency` (new: within-chapter contradictions, distinct from `coherence` which checks logical flow) and `beta_reader` (new: simulated first-read feedback). Legacy values (`coherence`, `pacing`, `dialogue`, `tension`) stay on the API for power users but are no longer exposed in the UI.
+
+Cascade on chapter delete: when a chapter is removed, all review Markdown files whose filename contains the chapter's slug are deleted alongside the chapter row.
+
 ---
 
 ## Plugin routers

docs/audits/current-coverage.md

@@ -1,8 +1,50 @@
-# Test Coverage Audit - v0.17.0
+# Test Coverage Audit - v0.17.0 (with v0.20.0 addendum)
 
-Audit date: 2026-04-18
+Audit date: 2026-04-18 (primary), 2026-04-20 (v0.20.0 addendum below)
 Previous audit: 2026-04-13 (archived as `history/2026-04-13-coverage.md`)
-Scope: everything on `main` as of commit `decb531`.
+Scope: everything on `main` as of commit `decb531` (primary) plus
+the v0.19.1 -> v0.20.0 delta.
+
+## v0.20.0 addendum
+
+Delta since the 2026-04-18 primary audit:
+
+| Suite | 2026-04-18 | 2026-04-20 (v0.20.0) | Delta |
+|-------|-----------|----------------------|-------|
+| Backend (`backend/tests/`) | 511 | 638 | +127 |
+| Plugins in `make test` matrix | 409 | 409 | 0 |
+| Frontend (Vitest) | 351 | 405 | +54 |
+| E2E (Playwright smoke) | 135 passing / 31 failing | 162 passing / 0 failing / 4 skipped | +27 pass, -31 fail |
+| **Total automated tests** | 1,271 | 1,452 | +181 |
+
+### Gaps closed in the v0.20.0 window
+
+- **AI Review Extension**: 31 new backend tests across `test_ai_review.py` (47 total; includes prompt-builder for 8 languages, chapter-type injection, cost estimate, async review flow via JobStore + SSE, FileResponse download, cascade on chapter delete) and `test_ai_review_store.py` (15 direct unit tests: slugify, filename shape, report roundtrip, cascade boundary safety, DELETE chapter cascade integration).
+- **Backup regressions**: `test_backup_import_revive.py` pins 9 data-critical paths (soft-deleted book revival, idempotent live re-import, merge with non-empty DB, multi-doc YAML parse, smart-import project ZIP roundtrip, batch-export pandoc-skip gate).
+- **Playwright smoke for AI Review**: new `smoke/ai-review.spec.ts` (4 tests) covering the three radio focus buttons, non-prose warning visibility per chapter type, and a mocked happy-path download-report flow. Closes the step-7 protocol gap for the new UI feature.
+- **Frontend Vitest for AI Review**: `src/data/ai-review-strings.test.ts` (8 tests) pins 8-language coverage of the book-language status + warning strings and the non-prose chapter-type set's parity with the backend `NON_PROSE_TYPES` constant.
+- **Smoke test-infra cleanup**: `dashboard-filters` selector narrowed, content-safety recovery seed fixed, Ctrl+Z timing, theme reload seed via page.evaluate, export content-type tolerance, trash restore view switch, Classic first-line-indent CSS specificity, CreateBookModal Select testid, dashboard sort direction expectation, export dialog migrated to download event, word-count + viewport-zoom tracked as skipped with issue #9 references.
+
+### Still open as of v0.20.0
+
+- **Audiobook generation E2E** - still no dedicated smoke spec; same as 2026-04-18.
+- **Image/asset upload in editor E2E** - still no spec.
+- **TipTap useEditor -> React re-render for status bar** - currently ships with a stale word count on keyboard input. Lessons-learned has the subscribe pattern documented; dedicated fix + test un-skip is deferred to post-v0.20.0.
+- **Chapter-sidebar dropdown layout at 125% / 150% CSS zoom** - 3 skipped smoke tests; needs Radix Popper collision rework or a viewport-downscale test proxy.
+
+### v0.20.0 running totals
+
+| Suite | Count |
+|-------|-------|
+| Backend only | 638 |
+| Plugins via `make test` matrix | 409 |
+| Total Python tests in repo | 1,047 |
+| Frontend (Vitest) | 405 |
+| E2E (Playwright smoke) | 162 passing / 4 skipped |
+
+---
+
+## Primary audit (2026-04-18 baseline)
 
 ## Deltas since 2026-04-13
 

docs/help/de/ai.md

@@ -41,14 +41,44 @@ Die KI passt ihre Vorschläge an das Genre und die Sprache deines Buches an.
 
 ## Kapitel-Review
 
-Klicke den **Review**-Tab im KI-Panel. Die KI analysiert das gesamte Kapitel und gibt strukturiertes Feedback:
+Klicke den **Review**-Tab im KI-Panel. Die KI analysiert das gesamte Kapitel und liefert einen strukturierten Markdown-Bericht, den du speichern und wieder öffnen kannst.
+
+### Fokusmodi
+
+Wähle genau einen Fokus, bevor du **Kapitel reviewen** anklickst:
+
+- **Stil** - Schreibstil: Wortwahl, Satzvariation, Lesbarkeit, Stimmkonsistenz. Nutze diesen Modus, wenn die Story funktioniert, die Prosa aber geschliffen werden soll.
+- **Konsistenz** - Widersprüche innerhalb des Kapitels: Fakten, Zeitlinie, Figurenmerkmale, Orte, Objektbeschreibungen. Fängt die kleinen "ihr Mantel war vor zwei Seiten blau, jetzt grün"-Fehler ab, bevor sie ein Leser entdeckt.
+- **Testleser** - offenes Erstleser-Feedback: Was zieht rein, was zieht sich, was verwirrt, welche Fragen bleiben offen. Nutze diesen Modus, wenn das Kapitel fertig ist und du einen "frische Augen"-Durchgang willst.
+
+Die vier Legacy-Fokuswerte (Kohärenz, Pacing, Dialog, Spannung) sind auf API-Ebene weiterhin verfügbar, tauchen aber nicht mehr im UI auf.
+
+### Kostenschätzung
+
+Der Start-Button zeigt eine grobe Schätzung der Input-Tokens und der USD-Kosten basierend auf Kapitellänge und konfiguriertem Modell (z.B. `~5k Tokens, ~$0.075`). Die Schätzung ist konservativ; die tatsächliche Nutzung liegt meist darunter. Ohne bekanntes Modell erscheint keine Kostenangabe.
+
+### Nicht-Prosa-Kapitel
+
+Für Kapiteltypen, die keine erzählende Prosa sind (Titelseite, Copyright, Inhaltsverzeichnis, Impressum, Index, Schmutztitel, Auch-vom-Autor, Nächster-Band, Call-to-Action, Endnoten, Literatur, Glossar), zeigt Bibliogon eine kleine Warnung über dem Start-Button. Du kannst das Review trotzdem starten; das Feedback ist dann meist eingeschränkter als bei Prosa.
+
+### Strukturiertes Ergebnis
+
+Jedes Review nutzt die gleiche Struktur:
 
 - **Zusammenfassung** - ein Satz zum Kapitelinhalt
 - **Stärken** - was gut funktioniert, mit konkreten Verweisen
 - **Vorschläge** - konkrete Verbesserungen mit Erklärungen
 - **Gesamtbewertung** - eine kurze Einschätzung
 
-Das Review berücksichtigt das Genre deines Buches und gibt genregerechtes Feedback (z.B. Pacing-Feedback für Thriller, Klarheits-Feedback für Sachbücher).
+Das Review berücksichtigt Genre, Sprache (alle 8 unterstützten UI-Sprachen) und den ausgewählten Kapiteltyp, so dass das Feedback zum jeweiligen Abschnitt passt (z.B. Pacing-Feedback für Thriller, minimale Ton-Hinweise bei einer Widmung, Compliance-Hinweise auf Copyright-Seiten).
+
+### Persistenz + Download
+
+Jedes Review wird als Markdown-Datei unter `uploads/{book_id}/reviews/` gespeichert, Dateiname nach dem Schema `{review-id}-{kapitel-slug}-{YYYY-MM-DD}.md`. Ein **Bericht herunterladen**-Button erscheint neben dem Ergebnis, so kannst du die Datei lokal sichern, in ein Schreib-Notizbuch legen oder an einen Commit hängen. Beim Löschen eines Kapitels werden die zugehörigen Review-Dateien automatisch mit aufgeräumt.
+
+### Asynchroner Fortschritt
+
+Grosse Kapitel brauchen 5-60 Sekunden. Das Review läuft als Hintergrund-Job; der Editor bleibt bedienbar, und eine rotierende Statusmeldung (in der Sprache deines Buches) zeigt den Fortschritt. Du kannst das KI-Panel mitten im Review schliessen; sobald das Review fertig ist, taucht das Ergebnis beim erneuten Öffnen wieder auf.
 
 ## Marketing-Texte
 

docs/help/en/ai.md

@@ -41,14 +41,44 @@ The AI adapts its suggestions to your book's genre and language.
 
 ## Chapter review
 
-Click the **Review** tab in the AI panel. The AI analyzes your entire chapter and provides structured feedback:
+Click the **Review** tab in the AI panel. The AI analyzes your entire chapter and returns a structured Markdown report you can save and re-open.
+
+### Focus modes
+
+Pick exactly one focus before clicking **Review chapter**:
+
+- **Style** - writing style: word choice, sentence variety, readability, voice consistency. Use this when the story works but the prose needs polish.
+- **Consistency** - internal contradictions within the chapter: facts, timing, character traits, locations, object descriptions. Use this to catch the small "her coat was blue two pages ago, now green" kind of mistakes before a reader spots them.
+- **Beta Reader** - open-ended first-read feedback: what engages, what drags, what confuses, questions left in the reader's mind. Use this when the chapter is done and you want a "fresh eyes" pass.
+
+The three legacy focus values (Coherence, Pacing, Dialogue, Tension) are still supported on the API level for power users but are no longer exposed in the UI.
+
+### Cost estimate
+
+The Start button shows a rough input-token count and USD cost estimate based on your chapter length and the configured model (e.g. `~5k tokens, ~$0.075`). The estimate is conservative; actual usage is usually lower. No estimate is shown when the model is unknown to Bibliogon's price table.
+
+### Non-prose chapters
+
+For chapter types that are not narrative prose (title page, copyright, table of contents, imprint, index, half title, also-by-author, next-in-series, call-to-action, endnotes, bibliography, glossary), Bibliogon shows a small warning above the Start button. You can still run a review; the feedback may be more limited than for prose.
+
+### Structured output
+
+Every review uses the same structure:
 
 - **Summary** - one sentence about the chapter's content
 - **Strengths** - what works well, with specific references
 - **Suggestions** - concrete improvements with explanations
 - **Overall** - a brief assessment
 
-The review considers your book's genre and provides genre-appropriate feedback (e.g. pacing feedback for thrillers, clarity feedback for non-fiction).
+The review considers your book's genre, language (all 8 supported UI languages), and the selected chapter type, so feedback is appropriate to the section (e.g. pacing feedback for thrillers, minimal tone notes on a dedication, compliance hints on copyright pages).
+
+### Persistence + download
+
+Every review is saved as a Markdown file under `uploads/{book_id}/reviews/` with a filename like `{review-id}-{chapter-slug}-{YYYY-MM-DD}.md`. A **Download report** button appears next to the result so you can save the file locally for a writing notebook, attach it to a commit, or keep a history per chapter. When a chapter is deleted, its review files are automatically cleaned up alongside the chapter content.
+
+### Async progress
+
+Large chapters can take 5-60 seconds. The review runs as a background job; the editor stays usable, and a rotating status message (in your book's language) is shown while the analysis runs. You can close the AI panel mid-review; when the review finishes, the result re-appears on reopen.
 
 ## Marketing text