kolega-code 0.25.2__tar.gz → 0.26.1__tar.gz

{kolega_code-0.25.2 → kolega_code-0.26.1}/CHANGELOG.md

@@ -6,6 +6,195 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.26.1 - 2026-07-31
+
+### Fixed
+
+- Gigacode resume now matches cached `agent()` results by call content instead
+  of call position, so completed work no longer re-runs after `pipeline()`
+  timing drift or script edits that shift call positions (one production resume
+  had salvaged only 6 of 91 completed calls). Resumed runs also journal what
+  they replayed, making a resume of a resume exact, and a duplicate `agent()`
+  label now logs a one-time authoring hint. Existing journals work unchanged.
+- Workflow scripts now have a designated drafting location. The authoring
+  guide and `script_path` docs direct models to draft long scripts in the
+  session scratchpad instead of the project working tree — generated scripts
+  in the repo pollute `git status` and go stale for later sessions. The
+  executed script is persisted under the run directory either way.
+- Workflow token budgets are harder to undersize by accident. The
+  `token_budget` schema, tool docstrings, and authoring guide now carry
+  evidence-based sizing anchors (measured across real runs: review calls
+  median ~6k/p90 ~24k output tokens, coder calls median ~20k/p90 ~80k,
+  reasoning included — size as review_calls × 15k + coder_calls × 50k,
+  doubled, or omit), the run warns in the progress log at 75% and 90% spend,
+  and a run
+  that dies on budget exhaustion tells the model in its tool result that it is
+  resumable — with the exact `resume_from_run_id` call and the count of
+  journaled calls that will replay free.
+- Workflow fan-out failures are no longer silent. A `pipeline()` stage or
+  `parallel()` thunk that raises still drops its item to `None`, but the drop
+  is now reported live in the progress log and recorded in the transcript with
+  the exception and the offending script line; the `run_workflow` result warns
+  with an aggregate (e.g. `AttributeError at script line 299 (x6)`) and
+  `run.json` records `script_exception_drops`. A fan-out that comes back all
+  `None` with drops is called out as a likely script bug. Budget and agent-cap
+  exhaustion now propagate out of fan-outs and fail the run (cancelling and
+  draining the remaining chains) instead of shredding it into `None`s —
+  previously a run could report `completed` after a script bug silently
+  discarded every result.
+- An interrupted gigacode workflow's run id is now recoverable. Runs are
+  stamped with their owning session, cancelling a turn marks the run
+  `interrupted` in `run.json`, and the new session-scoped `list_workflow_runs`
+  tool lists this session's runs (status, tokens, journaled calls, artifact
+  paths) so the agent can resume an interrupted run with `resume_from_run_id`
+  instead of re-running it from scratch — previously the run id was only
+  returned on normal completion, so an interrupted run's journal was orphaned.
+
+## 0.26.0 - 2026-07-31
+
+### Added
+
+- **New bundled research and writing skills.** `deep-research` orchestrates
+  evidence-backed research and materializes cited reports, while `humanizer`
+  helps revise generated prose into more natural writing.
+- **OpenRouter provider.** `openrouter` (`OPENROUTER_API_KEY`) reaches the
+  OpenRouter gateway, shipping a generated catalog of every tool-capable
+  OpenRouter model with per-model context, output, vision, reasoning-effort and
+  edit-protocol metadata. Because the catalog runs to hundreds of models, the
+  Settings picker, `/model` and the sub-agent model catalog list OpenRouter's 20
+  most-used models — in the order of OpenRouter's own LLM Leaderboard — while
+  every other catalogued model stays selectable by exact ID via `--model`,
+  `/model`, `KOLEGA_CODE_MODEL` or `settings.json`. Reasoning effort maps to
+  OpenRouter's nested `reasoning` control, prompt caching is enabled
+  automatically, and `max_tokens` is deliberately not sent so an output cap
+  cannot bias upstream routing (override with
+  `KOLEGA_CODE_OPENROUTER_MAX_TOKENS`). Models default to the Claude Code-style
+  edit tool, except OpenAI models which use Codex `apply_patch`.
+- **`kolega-code models` command.** `models list` inspects the model catalog
+  (`--provider`, `--featured`, `--sort`, `--json`), and `models refresh` caches
+  OpenRouter's current model list locally so models published after a release
+  can be used without upgrading. Startup merges the cache without any network
+  access; `KOLEGA_CODE_OPENROUTER_CATALOG` and
+  `KOLEGA_CODE_DISABLE_OPENROUTER_CATALOG` control it.
+- **Settings "Other…" model picker.** The main Model dropdown and every Agent
+  Models role row lead with OpenRouter's most-used models and then offer an
+  "Other…" entry backed by a free-text field, so any catalogued model id
+  (bundled or added by `models refresh`) can be selected from Settings instead
+  of only by exact ID on the command line. Typed ids are validated against the
+  catalog before saving, and the Browser role keeps its vision-capability gate.
+- **Worktree-aware startup and workspace switching.** Interactive and headless
+  launches can select a registered checkout with `--worktree`, or create one
+  safely with `--create-worktree` plus optional `--from` and
+  `--worktree-path`. In the TUI, the top-level build-mode agent can switch its
+  complete active workspace between registered sibling worktrees, but only when
+  the user has explicitly asked it to: the agent never creates a worktree or
+  moves the session on its own initiative, plan mode has no workspace-switching
+  tool at all, and every agent-initiated switch is confirmed by the user first,
+  with a declined or unanswered prompt leaving the workspace unchanged. Once
+  approved, the switch commits immediately and applies at the end of the agent's
+  turn by rebuilding the workspace — terminal, filesystem, LSP, snapshots,
+  skills, autocomplete, and Changes/Rewind scope move together — after which the
+  agent is prompted to continue in the new checkout. Session identity and
+  sibling-checkout isolation remain unchanged, and active workspace selection
+  persists across resume.
+- The public `ToolExtension` API now accepts additive `exclusive_tools`
+  metadata for tools that must run alone in a model tool-call batch.
+- `browser_scroll` on both browser backends, taking exactly one of a target, a
+  count of viewports, or an absolute offset. On a page too large to snapshot in
+  one call, scrolling is how the rest is reached, and until now nothing could
+  move the viewport on the Chrome backend at all.
+
+### Changed
+
+- The TUI `set_goal` tool is now build-mode only. Plan mode's tool inventory is
+  meant to be read-only plus investigation, and a planning turn should not be
+  able to start an autonomous loop on its own; `/goal <condition>` still works in
+  either mode, and a goal set in build mode keeps driving turns after switching
+  to plan mode.
+- Project memory, repository guidance (`AGENTS.md`/`KOLEGA.md`), and the current
+  date are no longer rendered into the system prompt. They now reach the agent as
+  `<system-reminder>` context updates, sent once each time they change. Because
+  providers cache on a prefix match and the system prompt is processed ahead of
+  every message, a single `edit_memory` call previously invalidated the cached
+  prefix for the whole conversation and re-billed it on the next turn — on the
+  order of a dollar per write in a long session, and worse on providers whose
+  prefix caching is automatic and offers no way to compensate. The system prompt
+  is now byte-stable for the life of a session.
+- Prompt-cache breakpoints are placed more deliberately: the tool list and the
+  system prompt each get one with a 1-hour TTL, and the conversation carries two
+  rolling breakpoints a turn apart rather than one. A single trailing breakpoint
+  could fail to match after a turn with many parallel tool calls, which discarded
+  the whole conversation's cache; the second one bounds that loss to one turn.
+
+- The Chrome browser backend now works on large real-world pages. Selector
+  resolution, snapshots, text search and focus handling previously failed
+  outright on any page over about a thousand DOM nodes, so an ordinary
+  application page returned an empty snapshot and refused every selector. Work
+  is now bounded by a wall-clock budget with the browser's own APIs doing the
+  filtering, and a bound that is reached degrades with a report instead of
+  failing.
+- Snapshots emit the nodes nearest the viewport first and attach a `Coverage:`
+  line naming what was omitted, why, and where the viewport sits in the page, so
+  a partial snapshot reads as "narrow the scope" rather than "the page is
+  unreadable".
+- `browser_find` distinguishes three outcomes: absent from the page, present but
+  outside the region the snapshot covered, and undetermined because the search
+  was truncated. Only the first is a reliable absence.
+- Text waits that could not read the whole page now fail immediately with a
+  `search_truncated` explanation instead of polling to a timeout and implying the
+  text was not there.
+- `browser_press_key` scrolls for `PageDown`, `PageUp`, `Home`, `End`, arrow keys
+  and `Space`, matching the Playwright backend, unless the page handles the key
+  itself or focus is in a text field or select.
+- Chrome snapshot `depth` now counts emitted nodes rather than raw DOM nesting,
+  so it means roughly what it means on the Playwright backend.
+- Tall full-page screenshots on Chrome are clipped from the current scroll
+  position and report the omission, instead of being downscaled until unreadable.
+  Native Messaging envelopes are now bounded per direction, following Chrome's
+  own asymmetric limits.
+- Errors from the Chrome extension keep their error code, and codes that mean
+  "too large to cover in one call" carry the concrete next step.
+- The responsiveness watchdog now captures stacks for event-loop stalls from ~1
+  second (was 5) and counts shorter gaps into a periodic `loop_gap_histogram`
+  diagnostics entry, so choppy-but-not-frozen UI leaves evidence instead of
+  nothing. Stack dumps are capped per session so a pathological session cannot
+  fill the timeline.
+- `read_image` now refuses files above 20 MB (the limit image encoding already
+  applied elsewhere) instead of reading them and having the provider reject the
+  request.
+
+### Fixed
+
+- Standalone generated `<system-reminder>` context no longer appears in the TUI
+  transcript after resuming a session or rebuilding the agent for model and
+  settings changes; the context remains unchanged in model and session history.
+- Continuing after cancelling an in-flight tool call no longer duplicates the
+  next prompt or makes Anthropic reject the request for exceeding its maximum
+  of four `cache_control` blocks.
+- Plan mode now carries requested Build-mode session handoffs into approved
+  plans: worktree plans switch the complete session before setup or edits in
+  the linked checkout, and authorized autonomous-goal plans place `set_goal` at
+  the intended transition after any required prerequisites.
+- Stopped image-heavy sessions from freezing the TUI. Building request history
+  re-encoded every screenshot in history on every LLM request, on the event
+  loop — dozens of multi-second stalls per session, multiplied by each running
+  sub-agent. Resized copies are now memoized per image and dimension cap
+  (surviving the small byte-budget shifts a newly captured screenshot causes),
+  and the repair/adapt pass runs in a worker thread.
+- Moved LLM request preparation off the event loop. Building a request body is
+  proportional to conversation size, and on the Anthropic streaming path it
+  blocked the UI for 0.4 s per request with an image-heavy history — multiplied
+  by every concurrently running sub-agent. The worst event-loop gap per request
+  drops from 111 ms to 19 ms with 6 MiB of images in history, and from 425 ms to
+  69 ms at 24 MiB.
+- Stopped `web_fetch` from freezing the UI on large pages. Scoring an extraction
+  re-parsed the entire raw document on the event loop, once per extractor
+  attempt plus once more for single-page-app detection; the document is now
+  measured once per fetch in a worker thread. On an 11.6 MB page the worst
+  event-loop gap drops from 774 ms to 219 ms, and on a pathological 13.8 MB page
+  from 48 s to 0.5 s.
+- Moved `read_image`'s file read and base64 encode off the event loop.
+
 ## 0.25.2 - 2026-07-28
 
 ### Fixed

{kolega_code-0.25.2 → kolega_code-0.26.1}/CONTRIBUTING.md

@@ -99,6 +99,15 @@ Run the fast test suite before opening a pull request:
 ./run_tests.sh
 ```
 
+The wrapper runs tests in parallel using the available CPU cores. Set
+`PYTEST_WORKERS` to cap concurrency, or set it to `0` for a serial debugging
+run:
+
+```bash
+PYTEST_WORKERS=4 ./run_tests.sh
+PYTEST_WORKERS=0 ./run_tests.sh tests/test_git_env.py
+```
+
 Run slow and integration tests only when you have the required credentials:
 
 ```bash
@@ -108,7 +117,7 @@ Run slow and integration tests only when you have the required credentials:
 You can pass additional pytest arguments through the wrapper:
 
 ```bash
-./run_tests.sh tests/agent/llm/test_client.py -ra
+./run_tests.sh tests/test_git_env.py -ra
 ```
 
 ## Updating bundled skills

{kolega_code-0.25.2 → kolega_code-0.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.25.2
+Version: 0.26.1
 Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
@@ -236,6 +236,7 @@ Requires-Dist: filelock==3.20.3
 Requires-Dist: firecrawl-py==4.28.2
 Requires-Dist: google-genai==2.12.1
 Requires-Dist: httpx==0.28.1
+Requires-Dist: idna==3.18
 Requires-Dist: jinja2==3.1.6
 Requires-Dist: langfuse==3.14.5
 Requires-Dist: lxml-html-clean==0.4.5
@@ -269,6 +270,7 @@ Requires-Dist: pre-commit==4.6.0; extra == 'dev'
 Requires-Dist: pyright==1.1.411; extra == 'dev'
 Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist==3.8.0; extra == 'dev'
 Requires-Dist: pytest==9.0.3; extra == 'dev'
 Requires-Dist: ruff==0.15.12; extra == 'dev'
 Requires-Dist: twine==6.2.0; extra == 'dev'
@@ -276,7 +278,7 @@ Description-Content-Type: text/markdown
 
 # Kolega Code
 
-**Multi-agent coding in the terminal.**
+**A terminal coding agent where the model writes its own multi-agent workflows.**
 
 [![PyPI version](https://img.shields.io/pypi/v/kolega-code)](https://pypi.org/project/kolega-code/)
 [![Python versions](https://img.shields.io/pypi/pyversions/kolega-code)](https://pypi.org/project/kolega-code/)
@@ -286,67 +288,73 @@ Description-Content-Type: text/markdown
 [![Docs](https://img.shields.io/badge/docs-kolega--ai.github.io-blue)](https://kolega-ai.github.io/kolega-code/)
 [![Changelog](https://img.shields.io/badge/changelog-keep%20up-blue)](CHANGELOG.md)
 
-Kolega Code is a local-first terminal coding agent built for work that is too wide
-for one loop: fan out specialized sub-agents with **Gigacode**, route different
-models to different jobs, search the web, drive a browser, and keep sessions,
-settings, permissions, and credentials on your machine.
+Kolega Code is a local-first terminal coding agent. For work that is too broad
+for one agent loop, its **Gigacode** engine has the model write a Python program
+that orchestrates multiple sub-agents. The runtime then executes that program.
 
 ![Kolega Code in action](docs/src/assets/demo.gif)
 
-## Built for work one agent cannot cover
-
-Most terminal agents are strongest when one model can reason through one task at a
-time. Kolega Code keeps that familiar workflow, then adds orchestration for broad work:
-large audits, sweeping migrations, cross-file checks, adversarial reviews, and
-implementation plans whose pieces can run independently.
-
-With [Gigacode](https://kolega-ai.github.io/kolega-code/gigacode/), Kolega Code can:
-
-- **Fan out many sub-agents at once.** Split a wide codebase review by package,
-  assign independent implementation tasks, or run checks across many directories in
-  parallel.
-- **Use real workflow shapes.** The agent can generate parallel phases, pipelines,
-  loops, judge panels, and synthesis steps instead of only delegating one task at a
-  time.
-- **Keep orchestration visible.** Workflow phase headers and progress lines appear
-  in the transcript; the sub-agent inspector shows each agent's live trajectory.
-- **Save inspectable artifacts.** Each run keeps the generated workflow script,
-  result files, a Markdown transcript, raw JSONL, a resume journal, and debug
-  sub-agent transcripts under Kolega Code's state directory.
-- **Run in either mode.** In Plan mode, workflow sub-agents stay read-only for
-  parallel investigation. In Build mode, they can use the full coding toolset.
-- **Resume interrupted runs.** Finished workflow steps are journaled so a deliberate
-  resume does not have to restart the whole fan-out.
-
-Use normal chat for focused changes. Turn on Gigacode when the problem is broad
-enough that one serial agent pass would be the bottleneck.
-
-## Features
-
-- **Gigacode orchestration:** parallel, pipelined, looped, judged, and synthesized
-  multi-agent workflows with saved artifacts and resume support.
-- **Specialized sub-agents:** planning, building/coder, investigation, general, and
-  browser agents, with live activity tracking in the TUI.
-- **Repo tools:** read and search code, create files, apply precise edits, and inspect
-  session changes/diffs.
-- **Terminal execution:** run shell commands with streamed output and project-level
-  permission controls.
-- **Plan/build workflow:** use read-only Plan mode for investigation and a reviewable
-  task list, then Build mode to implement.
-- **Web search and browsing:** DuckDuckGo works by default with no key; Firecrawl,
-  Tavily, and SearXNG are configurable search backends. Kolega Code can also fetch URLs
-  directly and use a Playwright-powered browser agent for interactive sites.
-- **MCP servers:** connect verified `streamable_http`, `sse`, and `stdio` MCP servers
+## Gigacode: model-authored orchestration
+
+For a repo-wide review, a migration, or a plan with independent workstreams, the
+model writes an orchestration program instead of delegating workers one at a
+time. The program can combine parallel phases, pipelines, adversarial
+verification, judge panels, and synthesis gates to fit the task. The runtime
+saves the script so it can be inspected and run again.
+
+Claude Code uses the same model-authored approach for its dynamic workflows
+(ultracode). Kolega Code provides an open, provider-agnostic implementation
+whose runtime source is available in this repository.
+
+The runtime journals each completed agent call to disk. Resume is content-keyed
+rather than positional: when you use `resume_from_run_id`, calls with unchanged
+semantic inputs replay from the journal at zero token cost. This still works if
+the script was edited or reordered, and it works across sessions and process
+restarts.
+
+Read [how gigacode works](how-gigacode-works.md) for the architecture, or an
+[unedited model-authored workflow](examples/parallel-code-review.py) with its
+full provenance and execution record.
+
+## How it works
+
+The model investigates your repo, then writes a Python program against a small
+runtime API (`agent`, `parallel`, `pipeline`, `phase`, `budget`). The runtime
+enforces concurrency caps, an agent-count backstop, and token-budget accounting.
+It dispatches typed sub-agents, including read-only investigators, coders, and
+browser agents, whose activity streams into the TUI's sub-agent inspector.
+
+As the run progresses, the runtime writes the script, per-call results,
+transcripts, and final result to disk. An interrupted or budget-capped run keeps
+its journal and can be resumed, with unchanged calls replaying free. The
+mechanics, guarantees, and limitations are documented in
+[how-gigacode-works.md](how-gigacode-works.md).
+
+## The rest of the agent
+
+Gigacode is off by default. Enable it with `/gigacode on`. For focused changes,
+use Kolega Code as an ordinary terminal coding agent:
+
+- **Plan/Build modes:** read-only Plan mode for investigation and a reviewable
+  task list, Build mode to implement (`Shift+Tab` to switch). In Plan mode,
+  workflow sub-agents are forced read-only too.
+- **Repo tools:** read and search code, create files, apply precise edits, and
+  inspect session changes/diffs.
+- **Terminal execution:** run shell commands with streamed output and
+  project-level permission controls.
+- **Web search and browsing:** DuckDuckGo by default with no key; Firecrawl,
+  Tavily, and SearXNG configurable; direct URL fetch; a Playwright-powered
+  browser agent for interactive sites.
+- **MCP servers:** connect `streamable_http`, `sse`, and `stdio` MCP servers
   (including OAuth-enabled HTTP servers) as permission-gated tools.
-- **Model routing:** choose provider/model combinations, set thinking effort, split
-  long-context/fast/thinking roles, and override models per agent role.
-- **Interactive or scriptable:** use the Textual TUI, queue follow-up prompts
-  while the agent is working, run `kolega-code ask`, request JSON output,
-  list/export/resume sessions, and diagnose setup with `doctor`.
-- **Extensibility:** add agent skills, override prompts with project templates, run
-  lifecycle hooks, and persist project permission rules.
-- **Local-first state:** sessions, settings, permissions, OAuth tokens, and API-key
-  settings stay on your machine with restrictive permissions where applicable.
+- **Interactive or scriptable:** Textual TUI with queued follow-ups, one-shot
+  `kolega-code ask` with JSON output, session list/export/resume, `doctor`.
+- **Extensibility:** agent skills, project prompt-template overrides
+  ([docs](https://kolega-ai.github.io/kolega-code/configuration/prompt-overrides/)),
+  lifecycle hooks, persistent project permission rules.
+- **Local-first state:** sessions, settings, permissions, OAuth tokens, and
+  API-key settings stay on your machine with restrictive permissions where
+  applicable.
 
 ## Quick start
 
@@ -376,9 +384,9 @@ kolega-code .
 ```
 
 **3. Connect a model.** Complete the first-run wizard with ChatGPT sign-in or an
-API key. Later, open the categorized Settings screen from the sidebar or with
-`/settings`. Use `Shift+Tab` to switch between **Plan** and **Build** mode, or run
-`/gigacode on` when a task is broad enough for fan-out.
+API key. Later, open Settings from the sidebar or with `/settings`. Use
+`Shift+Tab` to switch between **Plan** and **Build** mode, or run `/gigacode on`
+when a task is broad enough for fan-out.
 
 Resume a previous conversation:
 
@@ -394,7 +402,7 @@ kolega-code . --resume <id>       # a specific Resume ID from `sessions list`
 | **Interactive TUI** | `kolega-code .` | Day-to-day development, exploration, orchestration |
 | **One-shot** | `kolega-code ask "…"` | Scripting, automation, quick questions, CI |
 
-There are also helper commands for managing sessions and checking your setup:
+Helper commands for sessions and setup:
 
 ```bash
 kolega-code ask "summarize this repository" --project .
@@ -402,10 +410,14 @@ kolega-code sessions list --project .
 kolega-code doctor --project .
 ```
 
-## Supported providers
+## Models and routing
 
-Kolega Code supports a broad model-provider catalog and lets you route models by
-role instead of forcing one model to do every job.
+Kolega Code can route models by role. You can use a strong long-context model
+for the main loop, a faster model for utility calls, and a dedicated model for
+extended thinking. Per-agent-role overrides are available for planning,
+building, investigation, general, and browser agents. A Gigacode workflow can
+also pin cheaper models to individual calls with `model_override`, allowing one
+model to write the orchestration while cheaper models run its agents.
 
 Supported model providers:
 
@@ -418,6 +430,7 @@ Supported model providers:
 - Fireworks.ai
 - xAI / Grok
 - DashScope / Qwen
+- OpenRouter (gateway to 250+ tool-capable models)
 - Moonshot / Kimi
 - DeepSeek
 - Z.AI / GLM Coding Plan
@@ -425,38 +438,21 @@ Supported model providers:
 - Ollama Cloud
 - local Llama
 
-Supported web-search backends:
-
-- DuckDuckGo — default, no key required
-- Firecrawl
-- Tavily
-- SearXNG — self-hosted option
+With a paid **ChatGPT** plan (Plus, Pro, or Business), `/login chatgpt` runs
+OpenAI models without a separate API key; tokens are stored locally (chmod `600`)
+and refreshed automatically. See
+[Sign in with ChatGPT](https://kolega-ai.github.io/kolega-code/configuration/sign-in-with-chatgpt/).
 
+Web search backends include DuckDuckGo (the default, with no key), Firecrawl,
+Tavily, and self-hosted SearXNG. Choose one in Settings or with
+`KOLEGA_CODE_WEB_SEARCH_BACKEND`.
 See [Providers & Models](https://kolega-ai.github.io/kolega-code/configuration/providers-and-models/)
 for model IDs, role configuration, API-key variables, and thinking-effort options.
 
-## Model routing
-
-Kolega Code can assign different models to different operational roles: a strong
-long-context model for the main coding loop, a faster model for utility calls, and
-a dedicated model for extended thinking. You can also override models per agent
-role — planning, building, investigation, general, and browser — so wide workflows
-can use cheaper models where they fit and stronger models where they matter.
-
-## Sign in with ChatGPT
-
-If you have a paid **ChatGPT** plan (Plus, Pro, or Business), you can use it to run
-OpenAI models instead of a separate API key. Run `/login chatgpt` in the TUI,
-complete the browser sign-in, and Kolega Code switches to the **OpenAI (ChatGPT
-subscription)** provider (default `gpt-5.6-sol`). Tokens are stored locally (chmod
-`600`) and refreshed automatically; `/logout chatgpt` removes them. See
-[Sign in with ChatGPT](https://kolega-ai.github.io/kolega-code/configuration/sign-in-with-chatgpt/).
-
 ## Configuration
 
-Set your provider, model, and API keys from first-run onboarding or the full-screen
-Settings editor in the UI, or via environment variables and flags for
-non-interactive use:
+Set provider, model, and API keys from onboarding or the Settings editor, or via
+environment variables and flags for non-interactive use:
 
 ```bash
 export KOLEGA_CODE_PROVIDER=deepseek
@@ -464,24 +460,12 @@ export DEEPSEEK_API_KEY=...
 kolega-code ask "summarize this repository" --project . --provider deepseek --model deepseek-v4-pro
 ```
 
-API key variables only provide credentials — pick a provider/model explicitly or
-save one in Settings. Local session state lives under your platform's state
+API key variables only provide credentials. Pick a provider and model explicitly
+or save them in Settings. Local session state lives under your platform's state
 directory unless `KOLEGA_CODE_STATE_DIR` is set. See the
 [Configuration docs](https://kolega-ai.github.io/kolega-code/configuration/settings-and-api-keys/)
 for the full story.
 
-The `web_search` tool uses DuckDuckGo by default without a key. To choose another
-backend, set it in **Settings** or export `KOLEGA_CODE_WEB_SEARCH_BACKEND` as
-`firecrawl`, `tavily`, or `searxng`; use `FIRECRAWL_API_KEY`, `TAVILY_API_KEY`, or
-`SEARXNG_BASE_URL` as needed.
-
-Projects can override Kolega Code's base prompts with uppercase Markdown templates
-in `.kolega/prompts/`. Generate editable starters with Jinja replacement tags using
-`/prompts dump` in the TUI or `kolega-code prompts dump --project .` in a terminal.
-To dump only selected starters, pass prompt names such as `coder`, `planning`, or
-`compaction` (filename aliases like `CODER.md` work too). Validate existing
-overrides with `/prompts validate` or `kolega-code prompts validate --project .`.
-
 ## Requirements
 
 - **Python 3.11+**
@@ -490,8 +474,12 @@ overrides with `/prompts validate` or `kolega-code prompts validate --project .`
 
 ## Documentation
 
+This repo includes the [Gigacode architecture document](how-gigacode-works.md)
+and an [unedited model-authored example workflow](examples/parallel-code-review.py).
+
 Full documentation lives at **[kolega-ai.github.io/kolega-code](https://kolega-ai.github.io/kolega-code/)**:
 
+- [Gigacode user guide](https://kolega-ai.github.io/kolega-code/gigacode/)
 - [Quick Start](https://kolega-ai.github.io/kolega-code/getting-started/quick-start/)
 - [CLI overview](https://kolega-ai.github.io/kolega-code/cli/overview/)
 - [How it works & concepts](https://kolega-ai.github.io/kolega-code/concepts/how-it-works/)