docs: stato della beta e documentazione completa della Biblioteca

[nikazzio]

Due commit, entrambi di sola documentazione.

1. Stato della beta dichiarato, requisiti in un posto solo

Porta su main la parte buona del riallineamento preparato sul ramo docs/beta-roadmap-alignment, che resta da parte per una decisione successiva, con le correzioni emerse dalla revisione.

• Pagina pubblica «Stato della beta» in italiano e inglese: cosa funziona oggi, cosa manca per ambito, limiti di dati e backup, e il fatto che le guide seguono main e possono precedere la versione installata. Voce in entrambe le barre laterali del sito.
• README: resta l'intestazione grafica (logo, sottotitolo, badge, più un badge per lo stato di beta), tornano la spiegazione delle tre modalità di traduzione, la tabella delle quattro fasi e l'elenco dei pacchetti per sistema. Tolto il rimando a STATO_SESSIONE_2.0.md, che è escluso dal repository e quindi era un collegamento morto.
• Requisiti di Node e npm dichiarati una volta sola, in package.json sotto engines (^20.19.0 || >=22.12.0, npm >=11), e citati dai documenti invece di essere riscritti a mano. La formulazione precedente — «22.12 o superiore nella serie 22.x» — escludeva Node 20.19 e Node 24, che Vite accetta.
• ARCHITECTURE: l'eccezione che consolida i cambi di schema nella baseline riprende la procedura concreta e riceve una condizione di uscita, la prima distribuzione a utenti esterni.
• PRODUCT_ARCHITECTURE: accanto a ciò che la beta non promette, cosa viene comunque preservato.
• ROADMAP: sezione «decisioni già chiuse, da non riaprire» e sorte operativa della proposta di rilascio chore(main): release glossa 2.0.0 #386.
• CONTRIBUTING: torna la tabella tipo di commit → incremento di versione, che un controllo automatico impone sui titoli delle proposte.
• Corretto un elenco spezzato nelle due pagine di ingresso del sito.

2. La Biblioteca documentata per intero

La guida pubblica descriveva catalogo, scheda e visore dentro un'unica sezione lunga, e la guida dentro l'applicazione non aveva nessuna sezione dedicata alla Biblioteca: quel poco che c'era viveva dentro «Archiviazione e lavori».

• Guida pubblica IT ed EN riscritte e riordinate lungo il percorso reale: differenza fra opera, digitalizzazione e versione locale; ricerca con le capacità dichiarate biblioteca per biblioteca; aggiunta al catalogo; catalogo con riga di dati, barra di completamento, comandi nel menu, filtri, ordinamento, viste salvate e collezioni; scheda dell'opera con le quattro linguette, «Altri metadati», «Dati tecnici», correzione dei dati e risincronizzazione; visore con provenienza, lettura solo locale, salvataggio della pagina aperta e zoom; scaricamento, verifica, riduzione e spazio; archivio e rimozione; impostazioni in tre linguette; limiti attuali dichiarati.
• Guida in-app: sezione «Biblioteca» nuova, prima di «Archiviazione e lavori», con lo stesso percorso in forma breve, in italiano e inglese.
• Regola di documentazione in CLAUDE.md e in docs-dev/README.md: ogni funzione nuova, rimossa o cambiata nel comportamento visibile si documenta nello stesso task in tre posti — guida in-app, pagine pubbliche IT ed EN, documento di sviluppo pertinente.

Verifiche

Sito costruito senza collegamenti morti (vitepress build), tipi e lint puliti, 1008 test su 116 file.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Unresolved documentation accuracy, duplicated requirements, lockfile synchronization, and formatting issues remain.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documentation-only PR aligning beta status, Library guidance, and development requirements across Italian and English surfaces.

Changes:

• Adds beta-status pages and navigation.
• Rewrites public and in-app Library documentation.
• Updates project requirements, contributor guidance, and architecture documentation.

File summaries

File	Description
src/stores/uiStore.ts	Adds the Library help section type.
src/i18n/it.json	Adds Italian Library help content.
src/i18n/en.json	Adds English Library help content.
src/components/help/HelpGuide.tsx	Adds Library help navigation and rendering.
README.md	Updates beta, setup, and verification guidance.
package.json	Declares Node and npm requirements.
docs/project/status.md	Adds Italian beta-status documentation.
docs/intro/getting-started.md	Updates Italian setup guidance.
docs/index.md	Corrects the Italian landing page.
docs/guides/library-discovery.md	Rewrites the Italian Library guide.
docs/en/project/status.md	Adds English beta-status documentation.
docs/en/intro/getting-started.md	Updates English setup guidance.
docs/en/index.md	Corrects the English landing page.
docs/en/guides/library-discovery.md	Rewrites the English Library guide.
docs/.vitepress/config.ts	Adds beta-status sidebar links.
docs-dev/ROADMAP_2_0.md	Records closed roadmap decisions.
docs-dev/README.md	Documents the three-surface documentation rule.
docs-dev/PRODUCT_ARCHITECTURE_2_0.md	Clarifies beta preservation guarantees.
docs-dev/ARCHITECTURE.md	Clarifies the schema-baseline procedure.
CONTRIBUTING.md	Updates contributor and version guidance.
CLAUDE.md	Adds documentation requirements.

Review details

Suppressed comments (19)

CONTRIBUTING.md:18

• The comment does not change the working directory, so copying this verification block from the repository root runs the Rust commands in the wrong directory. Make the directory change an actual command.

# From src-tauri:

README.md:125

• The comment does not change the working directory, so copying this verification block from the repository root runs the Rust commands in the wrong directory. Make the directory change an actual command.

# From src-tauri:

docs/en/guides/library-discovery.md:97

• This resync description promises that manual corrections are reapplied, but the implementation deletes every source_field_overrides row except Notes during resync (src/services/libraryService.ts:608-610). The guide should say that hand corrections are removed, while Notes and downloaded pages remain.

**Resync with the library** — The command in the data section header asks the library for the record again and updates what changed. Your corrections stay, because they are kept separately and are reapplied on top of the new data.

docs/en/guides/library-discovery.md:46

• The catalog filters archived works out by default (src/utils/libraryCatalogFilters.ts:29-30, 128-135), so saying it always shows every book contradicts both the implementation and the later archive instructions. State that non-archived works are shown by default and explain how to include archived ones.

The Library always shows **every book**: it is a catalogue, not the view of a workspace. The command above the results switches between list and grid.

docs/en/guides/library-discovery.md:185

• The English UI labels the first Library settings tab Settings (src/i18n/en.json:705), not Configurations. Using a different tab name here makes the documented Settings → Library path impossible to follow; use the visible label.

- **Configurations** — the network profiles, that is the pacing shared by several libraries, with explicit saving.

docs/en/guides/library-discovery.md:64

• The preceding paragraph describes workspace/collection chips and buttons that are direct row actions, so “no direct command on the row” contradicts the documented UI. Limit this sentence to the download/check/shrink/free-space/archive/remove actions in the overflow menu, or explicitly exclude link controls.

There is no direct command on the row: they all live in the **"···"** menu — download, check, shrink images, free space, and further down, after a separating line, archive and remove. The ones that do not apply right now stay in place, disabled, so you always know what can be done. Keeping the trash icon outside the menu would mean having it one click away on every row of a long catalogue.

docs/en/guides/library-discovery.md:68

• The implementation does not make every dropdown data-driven: work type always lists all supported kinds, availability always lists all three statuses, and workspace/collection list configured entities even when unused. This sentence overstates the UI; distinguish fixed choices from options derived from the visible catalogue.

**Filters** live in a right-hand column that resizes and collapses like the other side panels: its width and open state are remembered, and when it is closed a count says how many filters are active. Search sits at the top — type a title or an author — and below it work type, language, source library, availability, workspace and collection. The workspace filter shows the works linked to the one you pick, or — with the last entry — only those in no workspace at all. Filters work on what you already have in front of you, with no reload, and the dropdowns only offer values actually present in your catalogue. The eraser command clears everything.

docs/guides/library-discovery.md:97

• This resync description promises that manual corrections are reapplied, but the implementation deletes every source_field_overrides row except Notes during resync (src/services/libraryService.ts:608-610). The guide should say that hand corrections are removed, while Notes and downloaded pages remain.

**Risincronizza con la biblioteca** — Il comando nell'intestazione della sezione dei dati richiede di nuovo la scheda alla biblioteca e aggiorna quello che è cambiato. Le tue correzioni restano, perché sono conservate a parte e vengono riapplicate sopra i dati nuovi.

docs/guides/library-discovery.md:46

• The catalog filters archived works out by default (src/utils/libraryCatalogFilters.ts:29-30, 128-135), so saying it always shows every book contradicts both the implementation and the later archive instructions. State that non-archived works are shown by default and explain how to include archived ones.

La Biblioteca mostra **sempre tutti i libri**: è un catalogo, non la vista di un workspace. Il comando sopra i risultati alterna vista a elenco e vista a griglia.

docs/guides/library-discovery.md:64

• The preceding paragraph describes workspace/collection chips and buttons that are direct row actions, so “no direct command on the row” contradicts the documented UI. Limit this sentence to the download/check/shrink/free-space/archive/remove actions in the overflow menu, or explicitly exclude link controls.

Sulla riga non c'è nessun comando diretto: stanno tutti nel menu **«···»** — scarica, verifica, riduci le immagini, libera spazio, e più in basso, dopo un filo di separazione, archivia e togli. Quelli che in quel momento non servono restano al loro posto, spenti, così sai sempre cosa si può fare. Tenere il cestino fuori dal menu significherebbe averlo a un clic di distanza su ogni riga di un catalogo lungo.

docs/guides/library-discovery.md:68

• The implementation does not make every dropdown data-driven: work type always lists all supported kinds, availability always lists all three statuses, and workspace/collection list configured entities even when unused. This sentence overstates the UI; distinguish fixed choices from options derived from the visible catalogue.

I **filtri** vivono in una colonna a destra, che si ridimensiona e si richiude come gli altri pannelli laterali: la larghezza e lo stato aperto o chiuso si ricordano, e quando è chiusa un conteggio dice quanti filtri sono attivi. In cima c'è la ricerca — scrivi titolo o autore — e sotto tipo di opera, lingua, biblioteca di provenienza, disponibilità, workspace e collezione. Il filtro workspace mostra le opere collegate a quello che scegli, oppure — con l'ultima voce — solo quelle che non stanno in nessun workspace. I filtri lavorano su quello che hai già davanti, senza ricaricare niente, e le tendine offrono solo i valori davvero presenti nel tuo catalogo. Il comando con la gomma azzera tutto.

package.json:7

• Adding root engines metadata also requires regenerating the lockfile. package-lock.json still has no engines entry under its root packages["" ] object, so the committed lockfile is out of sync with this declaration.

  "engines": {
    "node": "^20.19.0 || >=22.12.0",
    "npm": ">=11"

src/components/help/HelpGuide.tsx:41

• This entry is flush with the left margin while every sibling in the sections array is indented, so the new help navigation is formatted inconsistently. Indent it to the same level as the surrounding entries.

{ id: 'storage',         label: t('help.sections.storage') },

src/i18n/en.json:1937

• The in-app help says resync reapplies manual corrections, but resync actually deletes all manual field overrides except Notes (src/services/libraryService.ts:608-610). This would mislead users about a destructive operation; describe the corrections as being removed and mention that Notes and downloaded pages are preserved.

      "editDesc": "Title, author, date and language can be corrected by hand: the pencil command opens the field, Enter saves, Esc cancels. The original data is never overwritten: the correction lives separately, a mark next to the label states it, hovering it you read what the library said, and a command restores the original. The resync command asks the library for the record again and updates what changed, reapplying your corrections on top of the new data.",

src/i18n/en.json:1931

• The preceding paragraph describes workspace/collection chips and buttons that are direct row actions, so “There are no direct commands on the row” contradicts the documented UI. Limit this sentence to the download/check/shrink/free-space/archive/remove actions in the overflow menu, or explicitly exclude link controls.

      "rowDesc": "The whole informative part of the row — cover, title, data — opens the work with one click, the same way in list and in grid. Under the title there is a data line with separators: source library, declared pages, sizes present on your computer and space used; with nothing local, the last entry reads \"online\". When something is there, a short bar appears at the end of the row with the count beside it, green and \"100%\" for a complete book, amber and \"120/328\" when pages are missing. There are no direct commands on the row: they all live in the menu, and archive and remove are separated from the others by a dividing line.",

src/i18n/en.json:1933

• The implementation does not make every dropdown data-driven: work type always lists all supported kinds, availability always lists all three statuses, and workspace/collection list configured entities even when unused. This sentence overstates the UI; distinguish fixed choices from options derived from the visible catalogue.

      "filtersDesc": "Filters live in a right-hand column that resizes and collapses like the other side panels; width and state are remembered, and when it is closed a count says how many filters are active. There are catalogue search, work type, language, library, availability, workspace and collection, plus sorting by title, author or date added. The dropdowns only offer values actually present in your catalogue. The bookmark command saves the filter combination as a view, recalled with one click. A collection is a label that gathers works from the same research without moving them, and one work can sit in several collections.",

src/i18n/it.json:1937

• The in-app help says resync reapplies manual corrections, but resync actually deletes all manual field overrides except Notes (src/services/libraryService.ts:608-610). This would mislead users about a destructive operation; describe the corrections as being removed and mention that Notes and downloaded pages are preserved.

      "editDesc": "Titolo, autore, data e lingua si correggono a mano: il comando con la matita apre il campo, Invio salva, Esc annulla. Il dato originale non viene mai sovrascritto: la correzione vive a parte, un segno accanto all'etichetta la dichiara, passandoci sopra leggi cosa diceva la biblioteca e un comando riporta all'originale. Il comando che risincronizza chiede di nuovo la scheda alla biblioteca e aggiorna quello che è cambiato, riapplicando le tue correzioni sopra i dati nuovi.",

src/i18n/it.json:1931

• The preceding paragraph describes workspace/collection chips and buttons that are direct row actions, so “There is no direct command on the row” contradicts the documented UI. Limit this sentence to the download/check/shrink/free-space/archive/remove actions in the overflow menu, or explicitly exclude link controls.

      "rowDesc": "Tutta la parte informativa della riga — copertina, titolo, dati — apre l'opera con un clic, allo stesso modo in elenco e in griglia. Sotto il titolo c'è una riga di dati a separatori: biblioteca di provenienza, pagine dichiarate, misure presenti sul computer e spazio occupato; se non hai niente in locale l'ultima voce è «online». Quando qualcosa c'è, in fondo alla riga compare una barra corta con il conteggio accanto, verde e «100%» a libro completo, gialla e «120/328» quando ne mancano. Sulla riga non ci sono comandi diretti: stanno tutti nel menu, e archivia e togli sono staccati dagli altri da un filo di separazione.",

src/i18n/it.json:1933

• The implementation does not make every dropdown data-driven: work type always lists all supported kinds, availability always lists all three statuses, and workspace/collection list configured entities even when unused. This sentence overstates the UI; distinguish fixed choices from options derived from the visible catalogue.

      "filtersDesc": "I filtri vivono in una colonna a destra che si ridimensiona e si richiude come gli altri pannelli laterali; larghezza e stato si ricordano, e a colonna chiusa un conteggio dice quanti filtri sono attivi. Ci sono ricerca nel catalogo, tipo di opera, lingua, biblioteca, disponibilità, workspace e collezione, più l'ordinamento per titolo, autore o data di aggiunta. Le tendine offrono solo i valori presenti davvero nel tuo catalogo. Il comando col segnalibro salva la combinazione di filtri come vista, richiamabile con un clic. Una collezione è un'etichetta che raccoglie opere della stessa ricerca senza spostarle, e una stessa opera può stare in più collezioni.",

• Files reviewed: 21/21 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.