docs: introduce Docusaurus docs site and simplify wiki

.github/workflows/ci.yml

@@ -102,6 +102,18 @@ jobs:
         path: .coverage
         include-hidden-files: true
 
+  ci:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    if: always()
+    steps:
+      - name: Check required jobs
+        run: |
+          if [[ "${{ needs.lint.result }}" != "success" || "${{ needs.test.result }}" != "success" ]]; then
+            echo "Required jobs failed: lint=${{ needs.lint.result }}, test=${{ needs.test.result }}"
+            exit 1
+          fi
+
   coverage-badge:
     needs: test
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'

.github/workflows/docs-ci.yml

@@ -24,7 +24,8 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
+          cache: 'npm'
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -36,20 +37,8 @@ jobs:
           npm install -g markdownlint-cli
           markdownlint "**/*.md"
 
-      - name: Link check
-        uses: lycheeverse/lychee-action@v2
-        with:
-          fail: true
-          args: >-
-            --no-progress
-            --verbose
-            --max-retries 3
-            --retry-wait-time 2
-            --timeout 20
-            --exclude-path .venv/**
-            --exclude-path node_modules/**
-            --exclude-file .lycheeignore
-            "**/*.md"
+      - name: Install docs dependencies
+        run: npm ci
 
       - name: Check docs language consistency
         run: |
@@ -59,10 +48,15 @@ jobs:
         run: |
           python scripts/check_docs_integrity.py
 
+      - name: Build Docusaurus docs
+        run: |
+          npm run docs:build
+
       - name: Check changelog policy
         run: |
           python scripts/check_changelog_policy.py
 
       - name: Check release consistency
         run: |
           python scripts/check_release_consistency.py
+

.github/workflows/docs-site.yml

@@ -0,0 +1,60 @@
+name: Docs Site
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - "src/css/**"
+      - "static/**"
+      - "docusaurus.config.js"
+      - "sidebars.js"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/docs-site.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-site
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build site
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/wiki-sync.yml

@@ -35,6 +35,7 @@ jobs:
             --repo "${{ github.repository }}" \
             --source-root "docs/wiki" \
             --wiki-dir "/tmp/iiif-wiki-sync-test" \
+            --docs-base-url "https://nikazzio.github.io/scriptoria/" \
             --dry-run
 
   publish-wiki:
@@ -60,5 +61,6 @@ jobs:
             --repo "${{ github.repository }}" \
             --source-root "docs/wiki" \
             --wiki-dir "/tmp/iiif-wiki-sync" \
+            --docs-base-url "https://nikazzio.github.io/scriptoria/" \
             --push \
             --commit-message "docs(wiki): sync from docs/wiki (${GITHUB_SHA})"

.gitignore

@@ -50,5 +50,7 @@ repomix-output*
 .vscode/
 .idea/
 *.swp
+node_modules/
+.docusaurus/
 PRIORITIES.md
 .claude/skills/

.lycheeignore

@@ -1,2 +1,7 @@
 http://127.0.0.1:8000
 http://localhost:8000
+https://img.shields.io/.*
+https://github.com/nikazzio/scriptoria/issues/new
+https://github.com/nikazzio/scriptoria/security/advisories/new
+https://nikazzio.github.io/scriptoria/.*
+/img/.*

CODE_OF_CONDUCT.md

@@ -105,17 +105,17 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct/][v2.1].
 
 Community Impact Guidelines were inspired by
 [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
 
 For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
+[https://www.contributor-covenant.org/faq/][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations/][translations].
 
 [homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+[Mozilla CoC]: https://github.com/mozilla/inclusion
+[FAQ]: https://www.contributor-covenant.org/faq/
+[translations]: https://www.contributor-covenant.org/translations/

README.md

@@ -79,9 +79,9 @@ Any IIIF-compliant manifest URL works directly.
 
 | | |
 | --- | --- |
-| 📘 [User Guide](docs/DOCUMENTAZIONE.md) | 🏗️ [Architecture](docs/ARCHITECTURE.md) |
-| ⚙️ [Config Reference](docs/CONFIG_REFERENCE.md) | 🌐 [HTTP Client](docs/HTTP_CLIENT.md) |
-| 📖 [Wiki](docs/wiki/Home.md) | 🗂️ [All Docs](docs/index.md) |
+| 🗂️ [Docs Home](https://nikazzio.github.io/scriptoria/) | 🚀 [Getting Started](https://nikazzio.github.io/scriptoria/intro/getting-started) |
+| 🏗️ [Architecture](https://nikazzio.github.io/scriptoria/explanation/architecture) | ⚙️ [Config Overview](https://nikazzio.github.io/scriptoria/reference/configuration) |
+| 💻 [CLI Reference](https://nikazzio.github.io/scriptoria/reference/cli) | 📖 [Wiki](https://github.com/nikazzio/scriptoria/wiki) |
 
 ## Development
 

docs/CONFIG_REFERENCE.md

@@ -1,14 +1,28 @@
 # Configuration Reference
 
-Single source of truth for runtime configuration keys used by this project.
+This page is the detailed reference for the runtime `config.json` used by Scriptoria. It is meant for operators, contributors, and advanced users who need the exact keyspace and the practical runtime meaning of each configuration family.
+
+Use [Configuration Overview](reference/configuration.md) if you want the conceptual map first. Use this page when you need to know exactly which key exists, what shape it expects, and how the application interprets it.
 
 ## Scope and Sources
 
-This reference documents the full `config.json` keyspace currently used by the app, based on:
-- `src/universal_iiif_core/config_manager.py` (`DEFAULT_CONFIG_JSON`)
-- `config.example.json`
+This reference documents the `config.json` keyspace currently used by the application, based on:
+
+- `src/universal_iiif_core/config_manager.py` and its runtime defaults;
+- validation logic in `src/universal_iiif_core/config_validation.py`;
+- `config.example.json`;
+- the active Settings UI panes that expose parts of the same tree.
+
+If a key appears in one source but not the others, this document should follow actual runtime behavior first and example files second.
+
+## How To Read This Reference
+
+The file is intentionally dense. A practical reading strategy is:
 
-If a key appears in one source but not the other, keep this document aligned with runtime behavior in `ConfigManager`.
+1. locate the top-level family you need;
+2. read the notes attached to that family, not only the raw keys;
+3. cross-check with the related UI pane if the key is user-editable from the web interface;
+4. treat validation and migration notes as part of the contract, because Scriptoria still carries some alpha-era legacy keys.
 
 ## Runtime Validation Policy
 
@@ -173,25 +187,24 @@ Behavior notes:
 ## `settings.library`
 
 - `settings.library.default_mode` (`string`, default: `operativa`)
-  - allowed: `operativa` | `archiviata`
-  - Determines the initial view mode displayed in the Library interface
-  - `operativa`: shows active/working documents (documents currently being processed or studied)
-  - `archiviata`: shows archived documents (completed or stored documents)
+  - allowed: `operativa` | `archivio`
+  - Determines the initial view mode displayed in the Library interface.
+  - `operativa` opens the working view oriented around active study items.
+  - `archivio` opens the archival view used for retained items and completed workspaces.
 
 ## `settings.ui`
 
 - `settings.ui.theme_preset` (`string`, default: `rosewater`)
 - `settings.ui.theme_primary_color` (`string`, default: `#7B8CC7`)
 - `settings.ui.theme_accent_color` (`string`, default: `#E8A6B6`)
-- `settings.ui.theme_color` (`string`, default: `#E8A6B6`)
 - `settings.ui.items_per_page` (`int`, default: `12`)
 - `settings.ui.toast_duration` (`int`, default: `3000`)
 - `settings.ui.studio_recent_max_items` (`int`, default: `8`, allowed range: `1..20`)
 - `settings.ui.polling.download_manager_interval_seconds` (`int`, default: `3`, allowed range: `1..30`)
 - `settings.ui.polling.download_status_interval_seconds` (`int`, default: `3`, allowed range: `1..30`)
 
 Notes:
-- `theme_color` is kept for backward compatibility; current UI uses primary/accent keys and preset.
+- `theme_color` is a legacy input accepted only during migration; `ConfigManager` rewrites it in-memory to `theme_accent_color` and removes the old key from the loaded tree.
 - Download polling values are used by Discovery HTMX fragments only (Download Manager and single status card).
 
 ## `settings.images`
@@ -200,8 +213,6 @@ Notes:
   - allowed: `balanced|quality_first|fast|archival|custom`
 - `settings.images.download_strategy_custom` (`string[]`, default: `['3000', '1740', 'max']`)
   - used only when `download_strategy_mode=custom`
-- `settings.images.download_strategy` (`string[]`, default: `['3000', '1740', 'max']`)
-  - canonical resolved strategy used at runtime (materialized from mode/custom)
 - `settings.images.stitch_mode_default` (`string`, default: `auto_fallback`)
   - allowed: `auto_fallback|direct_only|stitch_only`
 - `settings.images.iiif_quality` (`string`, default: `default`)
@@ -215,23 +226,35 @@ Runtime notes:
 - `download_strategy_mode` defines ordered direct size attempts before tile stitching.
 - The Studio `Std` button uses the same strategy as a normal volume download.
 - `download_strategy_custom` is an ordered attempt list (`3000`, `1740`, `max`), not a guarantee that `max` is larger than every explicit numeric attempt.
+- `download_strategy` is not a stable persisted config key anymore. Earlier configs may still contain it, but `ConfigManager` drops it and runtime recomputes the effective direct-attempt sequence from `download_strategy_mode` plus `download_strategy_custom`.
 - `stitch_mode_default` controls whether the standard volume strategy can fall back to stitching after direct attempts.
 - `iiif_quality` applies to normal page downloads and temporary remote high-res export fetches.
 - `probe_remote_max_resolution` drives the Studio thumbnail “Remote” informational line by probing `info.json`; it does not change download behavior.
 - local optimize keys are used by `POST /api/studio/export/optimize_scans` (in-place lossy rewrite of `scans/`).
 
 ## `settings.ocr`
 
-- `settings.ocr.ocr_engine` (`string`, optional in example config)
+- `settings.ocr.ocr_engine` (`string`, default: `openai`)
+  - allowed: `openai|anthropic|google_vision|kraken|huggingface`
 - `settings.ocr.kraken_enabled` (`bool`, default: `false`)
 
+Notes:
+- `settings.defaults.preferred_ocr_engine` seeds workflows that have not selected an engine explicitly.
+- `settings.ocr.ocr_engine` is the operational OCR engine used by Studio OCR flows.
+- The current Settings UI exposes `openai`, `anthropic`, `google_vision`, and `kraken`. Validation and OCR runtime also accept `huggingface`, so direct `config.json` editing can still select it.
+
 ## `settings.pdf`
 
 - `settings.pdf.viewer_dpi` (`int`, default: `150`)
 - `settings.pdf.viewer_jpeg_quality` (`int`, default: `95`)
 - `settings.pdf.prefer_native_pdf` (`bool`, default: `true`)
 - `settings.pdf.create_pdf_from_images` (`bool`, default: `false`)
 
+Notes:
+- `viewer_dpi`, `viewer_jpeg_quality`, `prefer_native_pdf`, and `create_pdf_from_images` are edited from the Settings `Processing Core` pane even though they live under `settings.pdf.*`.
+- `prefer_native_pdf=true` means Scriptoria will prefer a source PDF exposed by the upstream manifest when that produces a cleaner local acquisition path and no page subset has been requested.
+- `create_pdf_from_images=true` adds a compiled PDF artifact from local images when a native PDF was not used.
+
 ### `settings.pdf.export`
 
 - `settings.pdf.export.default_format` (`string`, default: `pdf_images`)
@@ -270,6 +293,7 @@ UI/runtime notes:
 - Studio item Output only selects one profile for the current job.
 - Studio item Output keeps profile selection as the primary control; job-specific overrides are optional and collapsed by default.
 - `max_parallel_page_fetch` is actively used for parallel remote high-res page staging.
+- `document_overrides` still exists in runtime because `pdf_profiles.py` can persist per-document override state, but it is not the main operator-facing control surface anymore.
 
 Backward compatibility:
 - legacy `settings.pdf.render_dpi` is mapped in-memory to:
@@ -282,6 +306,11 @@ Backward compatibility:
 - `settings.thumbnails.jpeg_quality` (`int`, default: `70`)
 - `settings.thumbnails.page_size` (`int`, default: `48`)
 - `settings.thumbnails.page_size_options` (`int[]`, default: `[24, 48, 72, 96]`)
+- `settings.thumbnails.studio_page_size_max` (`int`, default: `72`)
+
+Notes:
+- `page_size` and every entry in `page_size_options` are expected to stay in the `1..120` range.
+- `studio_page_size_max` is a runtime guard used by Studio thumbnail routes to cap oversized page-size requests even if the options list contains larger values.
 
 ## `settings.housekeeping`
 
@@ -354,6 +383,10 @@ Runtime notes:
 - `settings.viewer.mirador.openSeadragonOptions.maxZoomLevel` (`number`, default: `25`)
 - `settings.viewer.mirador.openSeadragonOptions.minZoomLevel` (`number`, default: `0.35`)
 
+Notes:
+- These values are presented in the Settings `Viewer > Zoom & Navigation` pane.
+- They shape the feel of the Mirador/OpenSeadragon canvas rather than the downloaded image quality itself.
+
 ## `settings.viewer.visual_filters.defaults`
 
 - `settings.viewer.visual_filters.defaults.brightness` (`number`, default: `1.0`)
@@ -401,3 +434,19 @@ Discovery search configuration. Editable from Settings > Discovery tab in the we
   - Clamped to [1, 50] at runtime and on save.
   - For paginatable providers (Archive.org, Harvard, LOC, Gallica), additional results can be loaded via the "Carica altri risultati" button.
   - Non-paginatable providers (Vatican, Bodleian, Cambridge, Heidelberg, Institut, e-codices) return at most this many results from a single API call.
+
+## Migration Notes
+
+Scriptoria is still carrying a small amount of alpha-era config migration logic. The important consequence is that a historical `config.json` may continue to load even after keys have moved.
+
+Currently migrated in-memory:
+
+- `settings.system.max_concurrent_downloads` -> `settings.network.global.max_concurrent_download_jobs`
+- `settings.system.download_workers` -> `settings.network.download.default_workers_per_job`
+- `settings.system.request_timeout` -> `settings.network.global.connect_timeout_s` and `settings.network.global.read_timeout_s`
+- `settings.pdf.render_dpi` -> `settings.pdf.viewer_dpi` and legacy `settings.pdf.ocr_dpi`
+- `settings.images.viewer_quality` -> `settings.pdf.viewer_jpeg_quality`
+- `settings.ui.theme_color` -> `settings.ui.theme_accent_color`
+- `settings.images.download_strategy` -> removed and recomputed at runtime
+
+This migration is non-destructive at runtime. It keeps old configs working, but the canonical file shape for new documentation and new edits is the one described in the sections above.