From a0f6f3081ae06328f0a451b3a3ef2959ca25721d Mon Sep 17 00:00:00 2001 From: Luis Novo Date: Sun, 4 Oct 2026 23:29:29 -0300 Subject: [PATCH] docs: defaults table matches the code; CHANGELOG entry for the docs overhaul (#1462) The Text-to-Speech default is read by nothing (podcasts use each speaker profile's voice model) and the Tools Model only backs API Ask calls without explicit models; the provider page now says so, matching the user guide. Co-authored-by: Claude Opus 5.5 --- CHANGELOG.md | 7 +++++++ docs/4-AI-PROVIDERS/index.md | 8 ++++---- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ac2bba3..9d5f0214 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed +- **Documentation rewritten against the code.** Every page under `docs/` was checked against v1.15.0 and rewritten where it described an older or imagined product (#1458, #1459, #1460, #1461): + - **Install:** one canonical path built on the shipped `docker-compose.yml`, with small override files for the Ollama and LM Studio variants. The network-exposure warning (bind ports to `127.0.0.1` or set a password) comes before the first `docker compose up -d`. Example encryption keys are generated, never copied. First-run setup lives in one place, [Connect a provider](docs/4-AI-PROVIDERS/index.md#connect-a-provider), and ends in a working chat via **Auto-assign Defaults**. The provider table is built from the provider registry: 24 providers, with the model types each one offers + - **User guide and concepts:** insights are a first-class concept and the context mode is *Insights only*. Ask is described as three stages. UI labels match the current app. Invented features are gone (tags, export/share, batch transformations, page-number citations and others). About 6,200 lines became about 1,450 + - **Configuration and troubleshooting:** `environment-reference.md` is the one complete list of variables, each marked with which process reads it. Troubleshooting entries start from the exact error message the app shows; a new page covers source processing and podcast failures. Security docs cover PBKDF2 credential encryption and the back-up-before-migrating warning + - **Development:** `architecture.md`, `testing.md`, `api-reference.md` and `code-standards.md` are rewritten from the code. A new playbook covers adding an AI provider. Dev setup lives on one page. The AGENTS files agree with the docs. Contributor conventions (Conventional Commits, CHANGELOG sections, pre-PR checks that match CI) are documented + ### Fixed - **Docs no longer recommend settings that do nothing.** `API_CLIENT_TIMEOUT` was never read by Open Notebook; the timeout guidance now covers what actually applies: `ESPERANTO_LLM_TIMEOUT` per model call (keep it below 600) and the web UI's 10-minute request limit (`NEXT_PUBLIC_API_TIMEOUT_MS`, build time only). Remaining `SURREAL_COMMANDS_MAX_TASKS` advice now uses `OPEN_NOTEBOOK_WORKER_MAX_TASKS`. Docker instructions no longer say to edit `.env` and `docker compose restart`: the shipped compose file doesn't load `.env` into the container and `restart` doesn't reload environment changes, so they now point to the `open_notebook` service's `environment:` block and `docker compose up -d` - **Timeouts no longer read as connection failures.** A model that doesn't answer within `ESPERANTO_LLM_TIMEOUT` used to report "Could not connect to the AI provider"; it now says the provider took too long and how to raise the limit. Connection failures (including connect timeouts) keep the old message diff --git a/docs/4-AI-PROVIDERS/index.md b/docs/4-AI-PROVIDERS/index.md index a617dbbe..2934a0af 100644 --- a/docs/4-AI-PROVIDERS/index.md +++ b/docs/4-AI-PROVIDERS/index.md @@ -1,6 +1,6 @@ # AI Providers -Open Notebook talks to AI models through providers. You connect a provider once in **Manage → Models**, pick which of its models to use, and choose a default model for each job (chat, embeddings, podcasts, transcription). +Open Notebook talks to AI models through providers. You connect a provider once in **Manage → Models**, pick which of its models to use, and choose a default model for each job (chat, embeddings, transcription and more). This page has three parts: @@ -51,13 +51,13 @@ Scroll down to **Default Model Assignments** on the same page. |---|---|---| | **Chat Model** | Yes | Notebook and source chat | | **Embedding Model** | Yes | Vector search and Ask | -| **Text-to-Speech Model** | No | Podcasts | +| **Text-to-Speech Model** | No | Not used yet: podcasts use the voice model set in each speaker profile | | **Speech-to-Text Model** | No | Transcribing audio and video sources | | **Transformation Model** | No (uses the chat model) | Transformations and insights | -| **Tools Model** | No (uses the chat model) | Ask (search planning) | +| **Tools Model** | No (uses the chat model) | Ask requests made through the API without explicit models (the Ask page uses the models picked there, which default to the chat model) | | **Large Context Model** | No (uses the chat model) | Any prompt over ~105K tokens is sent here automatically | -**Auto-assign Defaults** only fills Chat Model and Embedding Model. Set Text-to-Speech and Speech-to-Text by hand if you want podcasts or audio/video transcription. +**Auto-assign Defaults** only fills Chat Model and Embedding Model. Set Speech-to-Text by hand if you want audio/video transcription; for podcasts, pick a voice model in each speaker profile (**Podcasts → Profiles**). ### 5. Check that chat works