* docs: complete env reference; troubleshooting keyed on real error messages
Configuration (docs/5-CONFIGURATION):
- environment-reference.md is now the single complete list, checked
against the code and the content-core, esperanto, surreal-commands and
langsmith libraries: adds the undocumented variables, a "Read by"
column, correct defaults (SURREAL_COMMANDS_RETRY_ENABLED=false,
WAIT_MAX=60, LANGCHAIN_PROJECT=default, SurrealDB defaults), which
legacy provider vars Migrate to Database copies, and a table of
variables nothing reads.
- security.md: PBKDF2 derivation, POST /api/credentials/migrate-encryption
with the back-up-first / no-downgrade warning, password stored in
localStorage, full list of unauthenticated paths, real upload endpoint.
- reverse-proxy.md: drop v1.0 legacy sections and the non-existent
multi-container images; real /api/config output; how API_URL
auto-detection works; the 100 MB Next.js proxy cap.
- ai-providers.md, ollama.md, openai-compatible.md: one shared setup
procedure with current UI labels, provider/modality table from
provider_registry.py, no stale model lists or prices; Ollama
num_ctx and 180 s ESPERANTO_LLM_TIMEOUT; Azure form limits.
- local-tts.md is the shared Speaches page; local-stt.md keeps only
STT specifics (Whisper models, CCORE_AUDIO_SEGMENT_MINUTES).
- advanced.md, index.md, database.md: link to the reference instead of
re-listing variables; fix service names, port changes, backups.
Troubleshooting (docs/6-TROUBLESHOOTING):
- Entries start with the exact message from the code or the en-US
locale. New processing-issues.md covers queued/failed sources (the
content-core failure reasons), uploads, search, podcasts (profile
errors and NOTE hints). ai-chat-issues.md covers timeouts, error
classifier messages, empty responses, Ollama context, encryption
key and decryption errors.
- Removed invented entries ("too many connections", "Model is not a
LanguageModel: None", soft delete, retry vars as a connection fix).
SECURITY_REVIEW.md is marked as a historical January 2026 snapshot of
the credentials UI, with the SSRF and security-warning rows corrected.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: address review on configuration and troubleshooting pages
- No predictable keys or passwords: placeholders plus the openssl /
PowerShell generation commands used by the install docs.
- Every 0.0.0.0 bind and firewall rule (Ollama, OpenAI-compatible
servers, Speaches, LAN access) restricted to the host and Docker
networks or the LAN, with an explicit exposure warning.
- Diagnostic commands no longer print secrets.
- systemd drop-in includes [Service]; Traefik middleware attached to
the router.
- Provider pages link to Connect a provider (#1459) instead of
repeating steps; Vertex and keyless local providers called out;
"Add Selected" (a select-all toggle) no longer described as the add
button; "Manage -> Models" instead of "the Models page".
- Startup database failure described correctly (API down, not the
Database Connection Failed overlay); worker crash causes, Test
timeout/404 meanings, .env overrides when moving servers, frontend
restart from source, privacy claims scoped to self-hosted servers.
- Drop claims about bugs fixed in #1457; restore the ollama.md
GPU acceleration anchor used by quick-start-local.md.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: address second review round on configuration pages
- Anthropic Compatible always needs an API key and a Base URL
(enforced in api/models.py), noted in the provider differences.
- Speaches firewall guidance covers a separate Open Notebook host.
- The password check mirrors get_secret_from_env: a readable,
non-empty _FILE wins, otherwise the variable; never prints values.
- From source, frontend variables go in frontend/.env.local or the
shell: `make frontend` runs `next dev` in frontend/, which doesn't
read the root .env.
- The env listing prints every variable name, without values.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: correct the default API path for the frontend; deduplicate
Without API_URL the browser calls <host>:5055 directly (the /config
route auto-detects it); INTERNAL_API_URL only serves requests that hit
the Next.js /api forwarding. Full explanation stays in the environment
reference; the configuration index links to it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: upload limit depends on whether API calls go through the frontend proxy
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs: standardize Models navigation path to "Manage → Models"
The Models page (/settings/models) is rendered under the sidebar's
"Manage" section as a sibling of Settings, not as a child of it
(frontend/src/components/layout/AppSidebar.tsx). The docs mixed
"Settings → Models" (~150 occurrences) with the correct "Manage → Models"
(3). Standardize every doc, the backend error-message hints and the
speaches compose example on "Manage → Models". CHANGELOG is historical
and left untouched. No routes or behaviour changed.
Follow-up to the P2 note on #1313.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012heLWVTmopC5FkipUgnvsN
* docs: fix remaining multi-step "Settings → Models" instructions
Addresses cubic P2s on #1330: two sections spelled the old path out as
separate steps ("Click Settings… Select Models tab"), plus a few
shorthand "in Settings" mentions that refer to the Models page.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012heLWVTmopC5FkipUgnvsN
* docs: fix step numbering in quick-start-cloud after merging nav steps
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012heLWVTmopC5FkipUgnvsN
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
* refactor: rename "API Keys" settings page to "Models" (#1199)
Rename the provider credentials settings area from "API Keys" to "Models":
- Route: /settings/api-keys -> /settings/models with a permanent redirect
- UI copy: page title, description, and learn-more now use "Models" wording
- i18n: updated display values across all 14 locales (key names unchanged)
- Internal links: sidebar, setup banner, and command palette point to /settings/models
- Docs: "Settings → API Keys" references updated to "Settings → Models"
* docs(quick-start): update model settings navigation to Manage → Models
* fix(frontend): highlight only the active sidebar item on nested routes
Use longest-prefix matching so parent items like Settings don't also
highlight when viewing a child page such as Models. Add test coverage
for the Models page active state.
---------
Co-authored-by: Luis Novo <lfnovo@gmail.com>
Expose Esperanto's built-in omlx OpenAICompatibleProfile in Settings with
Ollama-style UX (default http://localhost:11435/v1, optional API key,
language+embedding discovery). No openai-compatible remapping or
OPENAI_COMPATIBLE_* env mirroring.
Fixes#1048
Co-authored-by: Luis Novo <lfnovo@gmail.com>
* docs: stop teaching 0.0.0.0 SurrealDB port exposure in setup snippets
Bind port 8000 to 127.0.0.1 in every compose and docker run snippet
(README, quick starts, installation, configuration and development docs,
and the examples/docker-compose-*.yml files), matching the shipped
docker-compose.yml from #1025. Drop the redundant --bind 0.0.0.0:8000
from containerized surreal start commands (it is the in-container
default) and add !override to docker-compose.override.yml.example so the
opt-in re-publish actually replaces the base port binding instead of
colliding with it. Docs that discuss reaching the database from another
machine now point at the override example plus a firewall/SSH-tunnel
note.
Closes#1034
* docs: parameterize creds in manual compose example, note Compose version for !override
The v1-latest image requires a separate surrealdb service unlike the
deprecated single-container image. Add comments pointing to the full
base docker-compose.yml in all partial code examples.
The v1-single image is being phased out ahead of v2. This adds
deprecation notices to the single-container docs and replaces
v1-latest-single image references with v1-latest across all
configuration guides and issue templates.
Closes#498
* feat: replace provider config with credential-based system (#477)
Introduce a new credential management system replacing the old
ProviderConfig singleton and standalone Models page. Each credential
stores encrypted API keys and provider-specific configuration with
full CRUD support via a unified settings UI.
Backend:
- Add Credential domain model with encrypted API key storage
- Add credentials API router (CRUD, discovery, registration, testing)
- Add encryption utilities for secure key storage
- Add key_provider for DB-first env-var fallback provisioning
- Add connection tester and model discovery services
- Integrate ModelManager with credential-based config
- Add provider name normalization for Esperanto compatibility
- Add database migrations 11-12 for credential schema
Frontend:
- Rewrite settings/api-keys page with credential management UI
- Add model discovery dialog with search and custom model support
- Add compact default model assignments (primary/advanced layout)
- Add inline model testing and credential connection testing
- Add env-var migration banner
- Update navigation to unified settings page
- Remove standalone models page and old settings components
i18n:
- Update all 7 locale files with credential and model management keys
Closes#477
Co-Authored-By: JFMD <git@jfmd.us>
Co-Authored-By: OraCatQAQ <570768706@qq.com>
* fix: address PR #540 review comments
- Fix docs referencing removed Models page
- Fix error-handler returning raw messages instead of i18n keys
- Fix auth.py misleading docstring and missing no-password guard
- Fix connection_tester using wrong env var for openai_compatible
- Add provision_provider_keys before model discovery/sync
- Update CLAUDE.md to reflect credential-based system
- Fix missing closing brace in api-keys page useEffect
* fix: add logging to credential migration and surface errors in UI
- Add comprehensive logging to migrate-from-env and
migrate-from-provider-config endpoints (start, per-provider
progress, success/failure with stack traces, final summary)
- Fix frontend migration hooks ignoring errors array from response
- Show error toast when migration fails instead of "nothing to migrate"
- Invalidate status/envStatus queries after migration so banner updates
* docs: update CLAUDE.md files for credential system
Replace stale ProviderConfig and /api-keys/ references across 8 CLAUDE.md
files to reflect the new Credential-based system from PR #540.
* docs: update user documentation for credential-based system
Replace env var API key instructions with Settings UI credential
workflow across all user-facing documentation. The new flow is:
set OPEN_NOTEBOOK_ENCRYPTION_KEY → start services → add credential
in Settings UI → test → discover models → register.
- Rewrite ai-providers.md, api-configuration.md, environment-reference.md
- Update all quick-start guides and installation docs
- Update ollama.md, openai-compatible.md, local-tts/stt networking sections
- Update reverse-proxy.md, development-setup.md, security.md
- Fix broken links to non-existent docs/deployment/ paths
- Add credentials endpoints to api-reference.md
- Move all API key env vars to deprecated/legacy sections
* chore: bump version to 1.7.0-rc1
Release candidate for credential-based provider management system.
* fix: initialize provider before try block in test_credential
Prevents UnboundLocalError when Credential.get() throws (e.g.,
invalid credential_id) before provider is assigned.
* fix: reorder down migration to drop index before table
Removes duplicate REMOVE FIELD statement and reorders so the index
is dropped before the table, preventing rollback failures.
* refactor: simplify encryption key to always derive via SHA-256
Remove the dual code path in _ensure_fernet_key() that detected native
Fernet keys. Since the credential system is new, always deriving via
SHA-256 removes unnecessary complexity. Also removes the generate_key()
function and Fernet.generate_key() references from docs.
* fix: correct mock patch targets in embedding tests and URL validation
Fix embedding tests patching wrong module path for model_manager
(was targeting open_notebook.utils.embedding.model_manager but it's
imported locally from open_notebook.ai.models). Also fix URL validation
to allow unresolvable hostnames since they may be valid in the
deployment environment (e.g., Azure endpoints, internal DNS).
* feat: add global setup banner for encryption and migration status
Show a persistent banner in AppShell when encryption key is missing
(red) or env var API keys can be migrated (amber), so users see
these prompts on every page instead of only on Settings > API Keys.
Includes a docs link for the encryption banner and i18n support
across all 7 locales.
* docs: several improvements to docker-compose e env examples
* Update README.md
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
* docs: fix env var format in README and update model setup instructions
Align the encryption key snippet in README Step 2 with the list
format used in the compose file. Replace deprecated "Settings →
Models" instructions with credential-based Discover Models flow.
* fix: address credential system review issues
- Fix SSRF bypass via IPv4-mapped IPv6 addresses (::ffff:169.254.x.x)
- Fix TTS connection test missing config parameter
- Add Azure-specific model discovery using api-key auth header
- Add Vertex static model list for credential-based discovery
- Fix PROVIDER_DISCOVERY_FUNCTIONS incorrect azure/vertex mapping
- Extract business logic to api/credentials_service.py (service layer)
- Move credential Pydantic schemas to api/models.py
- Update tests to use new service imports and ValueError assertions
* fix: sanitize error responses and migrate key_provider to Credential
- Replace raw exception messages in all credential router 500 responses
with generic error strings (internal details logged server-side only)
- Refactor key_provider.py to use Credential.get_by_provider() instead
of deprecated ProviderConfig.get_instance()
- Remove unused functions (get_provider_configs, get_default_api_key,
get_provider_config) that were dead code
---------
Co-authored-by: JFMD <git@jfmd.us>
Co-authored-by: OraCatQAQ <570768706@qq.com>
Add comprehensive documentation for setting up local speech-to-text
using Speaches with faster-whisper. Includes model recommendations,
GPU acceleration, Docker networking, and troubleshooting.
Also updates related docs with cross-references to the new guide.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Add pull_policy: always to all open_notebook service definitions
in docker-compose examples across documentation. This ensures
Docker always checks for and pulls newer images when running
docker compose up.
Closes#393
- Replace old docs structure with new comprehensive documentation
- Organize into 8 major sections (0-START-HERE through 7-DEVELOPMENT)
- Convert CONFIGURATION.md, CONTRIBUTING.md, MAINTAINER_GUIDE.md to redirects
- Remove outdated MIGRATION.md and DESIGN_PRINCIPLES.md
- Fix all internal documentation links and cross-references
- Add progressive disclosure paths for different user types
- Include 44 focused guides covering all features
- Update README.md to remove v1.0 breaking changes notice
