Merge branch 'main' into fix/issue-1221-ask-max-tokens

Author: lfnovo

.claude/skills/process-discussions/SKILL.md

@@ -14,8 +14,10 @@ and reply is approved by him before posting. You prepare; he decides.
 
 This process was calibrated by hand on 2026-08-16 across 10 Ideas
 (#1210–#1265) and re-run on 2026-09-02 (6 follow-ups + 3 new ideas), which
-added the `incubating` status and the pull rule. The patterns below are
-ratified practice, not theory.
+added the `incubating` status and the pull rule, and again on 2026-09-05
+(4 follow-ups), which added the one-decision-at-a-time format and the
+close-when-graduated-work-lands rule. The patterns below are ratified
+practice, not theory.
 
 **Ground rules:**
 
@@ -123,6 +125,16 @@ and close the Discussion as resolved (`closeDiscussion(reason: RESOLVED)`);
 an open thread with a final answer clutters the queue. Anyone can reopen
 with a new argument.
 
+**Close when graduated work lands** (ratified 2026-09-05). A thread whose
+needs have all either shipped or been routed elsewhere is done the moment
+the last fix is merged to `main` — do not wait for a versioned release.
+Post a closing reply that names the merged PR(s), says the change ships
+with the next release, and points testers at the `v1-dev` Docker image
+(rebuilt on every push to `main`), then close as resolved. Precedents:
+#1236 (editor bugs), #1243 (Crawl4AI token). Detecting this state is part
+of Phase 0: for every graduated Issue linked from an open thread, check
+whether it closed since the last run.
+
 **Graduation rules** (for `accepted → graduated` and `bug`):
 - Issue gets: Context (with Discussion origin link), Expected outcome,
   Out of scope, Acceptance criteria, References. Label `ready` (+ `bug` when
@@ -178,8 +190,23 @@ compliments about the question itself.
 
 ## Phase 4 — Approval gate, then post
 
-Present to the owner: ficha (compact), proposed outcome, full draft reply,
-and any issues/renames/closures the package includes. After approval:
+**One decision at a time** (owner preference, 2026-09-05). After the
+Phase 0 ledger, present decisions sequentially — never a batch. Each one
+uses this fixed format, in the owner's language:
+
+1. **ID + title**
+2. **Resumo** — what the thread is, how it was decomposed, current status
+3. **Último movimento** — who did what, when; what changed since the last run
+   (a graduated Issue closing, an upstream release, a user answering)
+4. **Sugestão ou dúvida** — the proposed outcome, the full draft reply,
+   and every side action the package includes (Issues to open, renames,
+   closures); or the concrete question when the call is the owner's. When
+   offering options, label them (a)/(b)/(c) and say which one you recommend
+
+On approval, execute the whole package in the order below (side actions
+first, reply last), report the URLs, then present the next decision.
+Number them ("Decisão 2 de 4") so the owner knows the size of the session.
+After approval:
 
 - Write bodies to scratchpad files; post via GraphQL (`addDiscussionComment`,
   `updateDiscussion` for renames) with `-F body=@file` — avoids shell

.env.example

@@ -23,10 +23,17 @@ SURREAL_NAMESPACE=open_notebook
 SURREAL_DATABASE=open_notebook
 
 # =============================================================================
-# OPTIONAL: AI Provider API Keys
+# DEPRECATED: AI Provider API Keys (environment-variable fallback)
 # =============================================================================
-# You can configure these via the UI (Settings → API Keys) or set them here
-# UI configuration is recommended for better security and flexibility
+# Configure AI providers via the UI: Settings → API Keys. Credentials are
+# stored encrypted, can be rotated without restarts, and support multiple
+# credentials per provider.
+#
+# The environment variables below are a DEPRECATED fallback. They still work
+# today, but there is no guarantee they keep working in future releases, and
+# new automation should not be built on them. A declarative provisioning
+# contract for headless/CI/Docker setups is being designed in
+# https://github.com/lfnovo/open-notebook/discussions/765
 
 # OpenAI
 # OPENAI_API_KEY=sk-...
@@ -47,10 +54,11 @@ SURREAL_DATABASE=open_notebook
 # External API URL (for webhooks, callbacks, etc.)
 # API_URL=http://localhost:5055
 
-# Ollama endpoint (if running locally)
+# Ollama endpoint — DEPRECATED fallback, configure via Settings → API Keys instead
 # OLLAMA_API_BASE=http://localhost:11434
 
-# oMLX (Apple Silicon) — prefer Settings → API Keys; port 11435 avoids SurrealDB on 8000
+# oMLX (Apple Silicon) — DEPRECATED fallback, configure via Settings → API Keys instead
+# Port 11435 avoids clashing with SurrealDB on 8000
 # OMLX_API_BASE=http://localhost:11435/v1
 # OMLX_API_KEY=  # optional; only if oMLX was started with --api-key
 

docs/5-CONFIGURATION/environment-reference.md

@@ -259,7 +259,7 @@ env | grep -E "^[A-Z_]+=" | sort
 - **Quote values:** Use quotes for values with spaces: `API_URL="http://my server:5055"`
 - **Restart required:** Changes take effect after restarting services
 - **Secrets:** Don't commit encryption keys or passwords to git
-- **AI Providers:** Configure via **Settings → API Keys** in the browser (not via env vars)
+- **AI Providers:** Configure via **Settings → API Keys** in the browser. The provider env vars listed under [Legacy](#legacy-ai-provider-environment-variables-deprecated) are a deprecated fallback
 - **Migration:** Use Settings UI to migrate existing env vars to the credential system. See [API Configuration](../3-USER-GUIDE/api-configuration.md#migrating-from-environment-variables)
 
 ---
@@ -283,7 +283,11 @@ Done!
 
 ## Legacy: AI Provider Environment Variables (Deprecated)
 
-> **Deprecated**: The following AI provider API key environment variables are deprecated. Configure providers via the Settings UI instead. These variables may still work as a fallback but are no longer recommended.
+> **Deprecated**: The following AI provider environment variables are a deprecated fallback. They still work today (the runtime reads the database first and falls back to the environment), but there is no guarantee they keep working in future releases, and new automation should not be built on them. Configure providers via **Settings → API Keys** instead.
+
+Why the UI is the source of truth: credentials in the database are encrypted at rest (via `OPEN_NOTEBOOK_ENCRYPTION_KEY`), can be added or rotated at runtime without restarts, and support multiple credentials per provider — none of which a single env var can express.
+
+**Headless, CI/CD and Docker deployments:** a declarative provisioning contract over the credentials API (a file describing providers and credentials, with `${VAR}`-style references resolved from the environment) is being designed in [Discussion #765](https://github.com/lfnovo/open-notebook/discussions/765). Until it ships, the env fallback is the only unattended path — use it knowing it is deprecated.
 
 If you have these variables configured from a previous installation, click the **Migrate to Database** button in **Settings → API Keys** to import them into the credential system, then remove them from your configuration.
 

docs/5-CONFIGURATION/ollama.md

@@ -45,15 +45,15 @@ ollama pull mxbai-embed-large  # Best embedding model for Ollama
 4. Click **Save**, then **Test Connection**
 5. Click **Discover Models** → **Register Models**
 
-**Legacy (Deprecated) — Environment variables:**
+**Environment variable fallback (Deprecated):**
 ```bash
 # For local installation:
 export OLLAMA_API_BASE=http://localhost:11434
 # For Docker installation:
 export OLLAMA_API_BASE=http://host.docker.internal:11434
 ```
 
-> **Note**: The `OLLAMA_API_BASE` environment variable is deprecated. Configure Ollama via Settings → API Keys instead.
+> **Deprecated**: `OLLAMA_API_BASE` is a deprecated fallback. It still works today, but there is no guarantee it keeps working in future releases, and new automation should not be built on it. Configure Ollama via **Settings → API Keys** instead. For headless/CI/Docker setups, see the [environment reference](environment-reference.md#legacy-ai-provider-environment-variables-deprecated) and the provisioning discussion in [#765](https://github.com/lfnovo/open-notebook/discussions/765).
 
 ## Network Configuration Guide
 
@@ -543,7 +543,7 @@ export OLLAMA_NUM_PARALLEL=4           # Parallel request handling
 export OLLAMA_FLASH_ATTENTION=1        # Enable flash attention (if supported)
 
 # Open Notebook configuration (configure via Settings → API Keys instead)
-# OLLAMA_API_BASE=http://localhost:11434  # Deprecated — use Settings UI
+# OLLAMA_API_BASE=http://localhost:11434  # Deprecated fallback — works today, no guarantee
 ```
 
 ### SSL Configuration (Self-Signed Certificates)