@goodandready/dsh-ollama-cloud-provider 0.0.0-stage → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## 0.1.3 — 2026-10-21
+
+- Aligned README documentation trio with dsh-documentation-standard: added standardized Hero headers, goodandready.app hub badges, support tables, and Mermaid architecture diagrams across English, Russian, and Chinese documentations.
+- Updated installation instructions and package version parity.
+
+## 0.1.2 — 2026-10-21
+
+- Test connection falls back to the reasoning text when a thinking model returns
+  no content, and uses a 64-token budget (#17).
+- Production acceptance of 0.1.1 confirmed chat, catalog and balance; the probe
+  is the only follow-up defect.
+
+## 0.1.1 — 2026-10-21
+
+Audit fixes (Gitea #1–#15):
+
+- A transient transport/timeout/server failure no longer cools down the only
+  configured account; the harness retry policy can recover. Credential and quota
+  rejections still cool the key (#1).
+- Removed the unimplemented `toolUpdate: 'addition-only'` declaration so the
+  model always receives the full tool list (#2).
+- `/dsh-ollama/key` and `/key/clear` only accept this plugin's credential
+  references (`apiKeyEnv`, configured account refs and `OLLAMA_*`) (#3).
+- The sidebar quota card honors `showSidebarQuota`, stays unmounted while the
+  setting is off and stops polling `/state` (#4).
+- The injected stylesheet carries `data-dsh-plugin` so neighbouring plugin
+  cleanup cannot strip it (#5).
+- Analytics uses the shared `estimateCost` implementation and applies
+  `priceOverrides` (#7).
+- Empty catch blocks report through `bestEffortFailed` at debug level (#8).
+- Removed unused modules and exports (`quota-runway`, `requireImages`,
+  `clearAnalyticsCache`, `PLUGIN_PROVIDERS`, `showUrlFor`) (#9).
+- Heatmap and theme values no longer hardcode colors (#10).
+- Test-connection requests disable thinking and use a 32-token budget (#11).
+- The request log is flushed on shutdown (#12).
+- Architecture documentation moved to `docs/design/ARCHITECTURE.md`; the
+  design contract lives in `docs/design/DESIGN.md` (#13).
+- Added wiring, analytics, route-guard and adapter regression tests (#14).
+- Account rows show the 7-day spend without a meaningless percentage (#15).
+
+## 0.1.0
+
+Initial release.
+
+- Registers the `ollama-cloud` provider route for DeepSeek Harness.
+- Native `/api/chat` transport (NDJSON) with thinking, tool calls, images and usage counters.
+- OpenAI-compatible `/v1/chat/completions` transport selectable per model.
+- Live model catalog from `/v1/models` enriched with `/api/tags` capabilities, plus an offline snapshot.
+- Balance from `/api/balance` (credits and legacy percentage windows) and spend from `/api/usage`
+  with 24-hour, 7-day and 30-day windows and per-model groups.
+- Multi-account rotation before the first streamed token, persistent cooldowns, sticky sessions and
+  model → account glob rules.
+- Price estimates including off-peak rates and per-model overrides.
+- Settings page, sidebar quota card, quota/analytics panel with a request heatmap, `/ollama` command,
+  TUI settings section and one-click plugin update.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-opencode-provider contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,15 @@
+dsh-ollama-cloud-provider
+Copyright (c) 2026 GooDAnDReaDY
+
+This product is MIT-licensed (see LICENSE).
+
+Third-party references and attribution:
+
+- The plugin structure, cordis lifecycle wiring, HTTP route guards, request log, analytics reader,
+  quota runway and generic client widgets were adapted from the author's own
+  `@goodandready/dsh-opencode-provider` (MIT).
+- The feature set was informed by `@goodandready/dsh-clinebot` (MIT) and
+  `@mars-sea/dsh-commandcode-provider` (MIT). No vendor code from those packages is bundled.
+- DeepSeek Harness packages (`@deepseek-ai/*`) are host-owned peer dependencies and are not bundled.
+- Ollama Cloud API facts were verified against the public documentation and live endpoints on
+  2026-10-21. Ollama is a trademark of its respective owner; this plugin is unofficial.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# 📦 @goodandready/dsh-ollama-cloud-provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+<h3>Ollama Cloud LLM Provider for DeepSeek Harness</h3>
+
+<p>
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/🌐_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-ollama-cloud-provider"><img src="https://img.shields.io/npm/v/@goodandready/dsh-ollama-cloud-provider?style=for-the-badge&color=crimson&logo=npm" alt="npm version"></a>
+  <a href="https://github.com/GooDAnDReaDY/dsh-ollama-cloud-provider/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="License"></a>
+</p>
+
+</div>
+
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
+---
+
+Ollama Cloud provider plugin for [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) (dsh).
+
+It registers one native LLM route, `ollama-cloud`, served by `https://ollama.com`, with two wire protocols:
+
+| Transport | Endpoint | When |
+|---|---|---|
+| `native` (default) | `POST /api/chat` | thinking, tool calls, usage counters |
+| `openai-chat` | `POST /v1/chat/completions` | OpenAI-compatible deployments and fallback |
+
+Requests resolve the key per call, so a changed credential reaches the next request without a restart.
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph DSH["DeepSeek Harness Core"]
+        Agent["DSH Agent / Chat"]
+        Creds["Credentials / launch env"]
+    end
+
+    subgraph Plugin["dsh-ollama-cloud-provider"]
+        Router{"Route: ollama-cloud"}
+        Pool["Account pool<br/>rotation, cooldowns, sticky"]
+        Catalog["Live catalog<br/>/v1/models + /api/tags"]
+        Usage["Balance & usage<br/>/api/balance + /api/usage"]
+
+        subgraph Transports["Wire protocols"]
+            T1["Native /api/chat (NDJSON)"]
+            T2["OpenAI /v1/chat/completions (SSE)"]
+        end
+    end
+
+    subgraph Ollama["Ollama Cloud"]
+        Chat["ollama.com/api/chat"]
+        OpenAI["ollama.com/v1/chat/completions"]
+        Billing["/api/balance, /api/usage"]
+    end
+
+    Agent --> Router
+    Creds -.-> Pool
+    Router --> Pool
+    Pool --> Transports
+    T1 --> Chat
+    T2 --> OpenAI
+    Catalog --> Router
+    Usage --> Billing
+```
+
+## Features
+
+- **Two wire transports** chosen per model: the native Ollama API (NDJSON) and the OpenAI-compatible gateway (SSE).
+- **Text, thinking, tool calls, images, usage and finish reasons** on both transports.
+- **Live catalog** from `GET /v1/models`, enriched with capability flags from `GET /api/tags`.
+- **Accurate limits** for the dsh picker: context window, input modalities, reasoning levels and their default, tool support, and API visibility.
+- **Balance and usage** from the official `/api/balance` and `/api/usage` endpoints: included credits, purchased credits, 24-hour / 7-day / 30-day spend, and spend by model.
+- **Multi-account rotation** before any content is streamed: 401/403/429 and quota rejections mark a key and retry with the next one. Cooldowns persist across restarts.
+- **Sticky accounts** per conversation, plus model → account glob rules.
+- **Price estimates** from the published Ollama pricing table, including off-peak rates, with per-model overrides.
+- **Browser UI**:
+  - **Settings → Ollama Cloud**: key, balance, accounts, rules, model allowlist, per-model transport, connection settings.
+  - **Sidebar quota card** (off by default, and it does not poll `/state` while disabled): a ring with the highest used window and rows with remaining credits or legacy windows.
+  - **Center quota panel**: spend windows, spend by model, accounts, routing trace, usage analytics and a request heatmap.
+- **`/ollama` command** for status, usage, balance, accounts, models, rules and `test [model]`.
+- **TUI settings section** for terminal profiles.
+- **One-click plugin update** in Settings → Ollama Cloud.
+
+## Install
+
+Build and pack first:
+
+```bash
+npm install
+npm run build
+npm pack
+```
+
+Install the published package:
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-ollama-cloud-provider@0.1.3
+# DSH Desktop:
+dsh plugin --profile desktop add @goodandready/dsh-ollama-cloud-provider@0.1.3
+```
+
+Or install the packed tarball into a profile:
+
+```bash
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.3.tgz
+# DSH Desktop:
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.3.tgz
+```
+
+Restart dsh (or DSH Desktop), then pick **Ollama Cloud** in the model picker.
+
+> **Use the tarball, not the directory.** On dsh 0.2.1-rc.2 the Desktop CLI aliases a local
+> directory passed to `dsh plugin add` and overwrites the target's `package.json`.
+
+## Configure
+
+```yaml
+- id: llm-ollama-cloud
+  name: "@goodandready/dsh-ollama-cloud-provider"
+  config:
+    apiKeyEnv: OLLAMA_API_KEY      # default
+    # apiKey: ...                  # composition only, never commit
+    transport: native              # native | openai-chat
+    requestTimeoutMs: 300000
+    streamIdleTimeoutMs: 300000
+    visibleModels: []
+    modelTransports: {}
+    # contextWindowOverrides: { "model-id": 131072 }
+    # maxOutputTokens: 32768
+    accounts:
+      - label: Work
+        apiKeyEnv: OLLAMA_API_KEY_2
+    activeAccount: ''              # label or credential name to pin
+    stickySession: true
+    showSidebarQuota: false
+```
+
+Every field except `apiKey` is volatile and appears in dsh settings.
+
+### Keys
+
+1. `config.apiKey` (composition only, `role('secret')`).
+2. The dsh credential seam under `apiKeyEnv` (default `OLLAMA_API_KEY`).
+3. The launch environment (process, project `.env`, `$DSH_HOME/.env`).
+
+Create a key at <https://ollama.com/settings/keys>. Keys do not expire; `x-api-key` is **not** accepted, only `Authorization: Bearer`.
+
+### Accounts and rotation
+
+Add a second account in **Settings → Ollama Cloud → Accounts**: give it a name and a credential reference (for example `OLLAMA_API_KEY_2`), paste its key, then Save. The default account always serves first unless `activeAccount` pins another one.
+
+Rotation happens **before any content is streamed**. When the serving key is rejected with an invalid credential, a rate limit or an exhausted quota, the adapter marks that key and retries the same request with the next usable account. A request that already started streaming is not replayed. Cooldowns are stored in `~/.dsh/storages/dsh-ollama/cooldowns.json` keyed by a SHA-256 fingerprint — raw keys are never written.
+
+### Model → account rules
+
+Pin a model to a preferred account with a glob. The first matching rule wins; `*` and `?` are supported and matching is case-insensitive. Other accounts remain fallbacks.
+
+```yaml
+modelAccountRules:
+  - pattern: "*flash*"
+    account: "Work"
+```
+
+## Balance and usage
+
+The plugin uses the documented cloud endpoints:
+
+- `GET /api/balance` → `included.balance_usd` / `included.allowance_usd` / `included.period` and `purchased.balance_usd`. Legacy accounts return `included.session.remaining_percent` and `included.weekly.remaining_percent`; both formats are displayed.
+- `GET /api/usage?range=24h|7d|30d&group_by=model` → totals and per-model groups with request count, USD, input, cached input and output tokens.
+
+`/api/usage` is limited to **10 requests per minute per user**, so the reader caches each range (balance 60 s, usage 120 s, failures 30 s) and never polls in the background. Quota failures are fail-open: chat never depends on them.
+
+## Settings page
+
+Open **Settings → Ollama Cloud**:
+
+- **Key** — status, paste a key, clear it, run **Test connection** against a chosen model. The probe disables thinking so the reply is visible.
+- **Balance and usage** — credit bar or legacy windows, spend windows, warning at 80 % and exhausted at 95 %.
+- **Accounts** — extra keys, per-account spend, pin, remove, set a key.
+- **Model → account rules** — glob rules.
+- **Routing** — sticky session per conversation.
+- **Models** — search, refresh the live catalog, hide models, override the wire transport per model, see price, context and capabilities.
+- **Connection** — native and OpenAI bases, usage and balance endpoints, transport, timeouts, output cap and context override.
+- **Sidebar** — show or hide the quota card.
+- **Plugin update** — current/latest version and **Update now**.
+
+The Host serves `/dsh-ollama/state`, `/health`, `/analytics`, `/usage`, `/balance`, `/config`, `/key`, `/key/clear`, `/refresh`, `/models/refresh`, `/test` and `/update`. Writes require JSON, are refused for cross-origin requests, and are restricted to loopback (`127.0.0.1` / `::1`).
+
+## Command
+
+```
+/ollama status            # provider, accounts, quota and model count
+/ollama usage             # 7-day spend windows and spend by model
+/ollama balance           # included and purchased credits
+/ollama accounts          # labels, source, active/cooling, 7-day spend
+/ollama models            # ids, price, context, capabilities
+/ollama rules             # model → account rules
+/ollama test [model]      # minimal real request
+```
+
+## Verified API facts
+
+Checked live on 2026-10-21:
+
+- `GET https://ollama.com/v1/models` is public and returns `data[]` plus a non-standard `models[]` array carrying `context_window`, `max_context_window`, `input_modalities`, `supported_reasoning_levels`, `default_reasoning_level`, `visibility` and `supported_in_api`.
+- `GET https://ollama.com/api/tags` is public and is the only per-model source of `capabilities` (`completion`, `tools`, `thinking`, `vision`).
+- The live catalog returned 23 cloud models.
+- Native `/api/chat` streams NDJSON and reports `prompt_eval_count`, `prompt_eval_cached_count`, `eval_count` and `done_reason` in the final line.
+- OpenAI `/v1/chat/completions` supports streaming, tools, vision, `reasoning_effort` and `stream_options.include_usage`.
+- Anthropic compatibility (`/v1/messages`) exists but is partial; this plugin does not use it.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run check         # typecheck + tests + build
+npm run release       # check + packed tarball
+node scripts/probe.mjs
+```
+
+`scripts/probe.mjs` is read-only against the public catalog; with `OLLAMA_API_KEY` set it also probes chat, balance and usage and prints the raw shapes.
+
+## Visual verification
+
+The Ollama Cloud settings page in DSH Desktop (dark theme): configured credential, balance and usage, and the connection probe.
+
+![Ollama Cloud settings](media/visual-verification.png)
+
+## Limitations
+
+- **Cloud only.** Local `http://localhost:11434` is not registered as a route.
+- Embeddings are not exposed: no cloud model in the live catalog advertises the `embedding` capability.
+- File attachments are forwarded as deterministic handle text, not inline bytes.
+- The usage endpoint is limited to 10 requests per minute; caches and the UI account for that.
+- Cost values are estimates from the published table (including off-peak rates); the gateway is the authority.
+- Automatic update requires the DSH CLI entry in the runtime.
+- The UI requires a web profile; the TUI keeps the `/ollama` command and the model route.
+
+## License
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY). See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/README.ru.md

@@ -0,0 +1,220 @@
+# 📦 @goodandready/dsh-ollama-cloud-provider
+
+<div align="center">
+
+<h3>Плагин-провайдер Ollama Cloud для DeepSeek Harness</h3>
+
+<p>
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/🌐_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e" alt="Витрина GoodAndReady"></a>
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-ollama-cloud-provider"><img src="https://img.shields.io/npm/v/@goodandready/dsh-ollama-cloud-provider?style=for-the-badge&color=crimson&logo=npm" alt="npm версия"></a>
+  <a href="https://github.com/GooDAnDReaDY/dsh-ollama-cloud-provider/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="Лицензия"></a>
+</p>
+
+</div>
+
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему Star на GitHub</strong> — это покажет мне, что плагин полезен, и добавит мотивации продолжать его развитие.
+      <br><br>
+      🐛 <strong>Если вы нашли баг или хотите предложить новую функцию</strong>, создайте Issue на GitHub на любом языке — я рассмотрю предложение и реализую полезные улучшения в одной из следующих версий плагина.
+    </td>
+  </tr>
+</table>
+
+---
+
+Плагин-провайдер **Ollama Cloud** для [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) (dsh).
+
+Плагин регистрирует один нативный LLM-маршрут `ollama-cloud` (`https://ollama.com`) и поддерживает два протокола передачи данных:
+
+| Транспорт | Эндпоинт | Назначение |
+|---|---|---|
+| `native` (по умолчанию) | `POST /api/chat` | thinking, вызовы инструментов (tool calls), счётчики usage (NDJSON) |
+| `openai-chat` | `POST /v1/chat/completions` | Совместимость с OpenAI API и резервный транспорт (SSE) |
+
+Ключи разрешаются динамически на каждый вызов: смена credential применяется мгновенно без перезапуска сервера.
+
+## Архитектура
+
+```mermaid
+graph LR
+    subgraph DSH["Ядро DeepSeek Harness"]
+        Agent["DSH Агент / Чат"]
+        Creds["Сервис учетных данных / окружение"]
+    end
+
+    subgraph Plugin["dsh-ollama-cloud-provider"]
+        Router{"Маршрут: ollama-cloud"}
+        Pool["Пул аккаунтов<br/>ротация, cooldown, sticky"]
+        Catalog["Живой каталог<br/>/v1/models + /api/tags"]
+        Usage["Баланс и расход<br/>/api/balance + /api/usage"]
+
+        subgraph Transports["Протоколы передачи"]
+            T1["Native /api/chat (NDJSON)"]
+            T2["OpenAI /v1/chat/completions (SSE)"]
+        end
+    end
+
+    subgraph Ollama["Ollama Cloud"]
+        Chat["ollama.com/api/chat"]
+        OpenAI["ollama.com/v1/chat/completions"]
+        Billing["/api/balance, /api/usage"]
+    end
+
+    Agent --> Router
+    Creds -.-> Pool
+    Router --> Pool
+    Pool --> Transports
+    T1 --> Chat
+    T2 --> OpenAI
+    Catalog --> Router
+    Usage --> Billing
+```
+
+## Полный обзор возможностей
+
+- **Два транспорта**, выбираемые индивидуально для каждой модели: нативный протокол Ollama API (NDJSON) и совместимый шлюз OpenAI (SSE).
+- **Поддержка всех режимов**: текст, reasoning/thinking, вызовы функций/инструментов, изображения (vision), подсчёт токенов и finish reasons на обоих транспортах.
+- **Живой каталог моделей**: автоматическое чтение `GET /v1/models`, дополненное флагами возможностей `capabilities` (`tools`, `thinking`, `vision`) из `GET /api/tags`.
+- **Точные лимиты и метаданные**: контекстное окно, входные модальности, уровни reasoning и значение по умолчанию, статус поддержки инструментов и видимость в API.
+- **Баланс и аналитика расхода**: интеграция с официальными облачными эндпоинтами `/api/balance` и `/api/usage` — включённые и купленные кредиты, расход за 24 часа / 7 дней / 30 дней, а также группировка по моделям.
+- **Пул аккаунтов с авто-ротацией до первого токена**: при получении 401, 403, 429 или ответа об исчерпании квоты ключ переводится в cooldown, а запрос автоматически перенаправляется на следующий доступный аккаунт. Состояния cooldown сохраняются между перезапусками по SHA-256 fingerprint.
+- **Sticky sessions**: закрепление одного аккаунта за конкретным диалогом, плюс гибкие правила `модель ➔ аккаунт` по glob-паттернам.
+- **Оценка стоимости**: тарификация по официальному прайс-листу Ollama Cloud, включая ночные скидки (off-peak rates) и возможность ручного переопределения цен на модель.
+- **Интерфейс в браузере (Web UI)**:
+  - **Настройки → Ollama Cloud**: управление ключами, отображение баланса, пул аккаунтов, правила маршрутизации, allowlist моделей, выбор транспорта.
+  - **Карточка квоты в сайдбаре**: кольцевой индикатор с наиболее загруженным окном и детализацией остатка кредитов (по умолчанию выключена и не нагружает сеть фоновыми опросами).
+  - **Центральная панель квот**: окна расходов, разбивка по моделям, трейс маршрутизации, аналитика токенов и интерактивный heatmap запросов.
+- **Команда `/ollama`**: статус провайдера, квоты, баланс, список аккаунтов, моделей, правил и запуск тестового запроса `test [model]`.
+- **Интеграция с терминалом (TUI)**: специальная секция настроек в терминальном режиме.
+- **One-Click обновление плагина**: прямая проверка npm registry и кнопка обновления в Web UI.
+
+## Установка
+
+Сборка и упаковка из исходного кода:
+
+```bash
+npm install
+npm run build
+npm pack
+```
+
+Установка опубликованного пакета из npm:
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-ollama-cloud-provider@0.1.3
+# DSH Desktop:
+dsh plugin --profile desktop add @goodandready/dsh-ollama-cloud-provider@0.1.3
+```
+
+Либо установка из упакованного tarball:
+
+```bash
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.3.tgz
+# DSH Desktop:
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.3.tgz
+```
+
+После установки перезапустите dsh (или DSH Desktop) и выберите **Ollama Cloud** в списке моделей.
+
+## Конфигурация
+
+```yaml
+- id: llm-ollama-cloud
+  name: "@goodandready/dsh-ollama-cloud-provider"
+  config:
+    apiKeyEnv: OLLAMA_API_KEY      # имя переменной или credential
+    # apiKey: ...                  # только в composition, не коммитить в git
+    transport: native              # native | openai-chat
+    requestTimeoutMs: 300000
+    streamIdleTimeoutMs: 300000
+    visibleModels: []
+    modelTransports: {}
+    accounts:
+      - label: Work
+        apiKeyEnv: OLLAMA_API_KEY_2
+    activeAccount: ''              # метка для принудительного закрепления
+    stickySession: true
+    showSidebarQuota: false
+```
+
+Все поля, кроме `apiKey`, доступны для изменения в интерфейсе настроек DSH.
+
+### Получение и хранение ключей
+
+1. `config.apiKey` в файле конфигурации (`role('secret')`).
+2. Системный сервис учетных данных DSH по имени `apiKeyEnv` (по умолчанию `OLLAMA_API_KEY`).
+3. Переменные окружения процесса, `.env` проекта или `$DSH_HOME/.env`.
+
+Ключ создается в личном кабинете: <https://ollama.com/settings/keys>. Ключи бессрочные; облачный API принимает только заголовок `Authorization: Bearer`.
+
+### Пул аккаунтов и ротация
+
+Дополнительный аккаунт добавляется в **Настройки → Ollama Cloud → Аккаунты**: укажите имя метки и credential reference (например, `OLLAMA_API_KEY_2`), вставьте токен и сохраните. Ротация происходит **строго до начала генерации потока**: отклонённый ключ получает cooldown, а запрос повторяется со следующим готовым аккаунтом.
+
+Состояния cooldown сохраняются в `~/.dsh/storages/dsh-ollama/cooldowns.json` по SHA-256 хешу ключа.
+
+### Правила привязки «модель ➔ аккаунт»
+
+```yaml
+modelAccountRules:
+  - pattern: "*flash*"
+    account: "Work"
+```
+
+Первый совпавший glob-паттерн направляет модель на указанный аккаунт, остальные аккаунты остаются в резерве.
+
+## Баланс и мониторинг расхода
+
+- `GET /api/balance` — поддерживает новый формат (`included.balance_usd`, `allowance_usd`, `period`, `purchased.balance_usd`) и legacy-формат (`session` / `weekly` с `remaining_percent`).
+- `GET /api/usage?range=24h|7d|30d&group_by=model` — суммарные показатели и разбивка по моделям.
+
+Эндпоинт `/api/usage` ограничен лимитом в **10 запросов в минуту**, поэтому баланс кэшируется на 60 секунд, статистика расхода — на 120 секунд. Фоновых опросов нет; временная недоступность квот не прерывает работу чата.
+
+## Страница настроек Web UI
+
+В разделе **Настройки → Ollama Cloud**:
+- **Key**: статус ключа, вставка, очистка, кнопка **Test connection**.
+- **Balance & Usage**: шкалы кредитов, окна расходов, предупреждения при 80% и 95%.
+- **Accounts**: управление пулом дополнительных учетных записей.
+- **Model rules**: настройка правил ротации по моделям.
+- **Models**: поиск, принудительное обновление каталога моделей, allowlist, переопределение транспорта.
+- **Connection**: базовые адреса, таймауты, лимиты токенов.
+- **Plugin update**: проверка обновлений и кнопка **Update now**.
+
+## Визуальная верификация
+
+Настройки и баланс Ollama Cloud в интерфейсе DSH Desktop (темная тема):
+
+![Настройки Ollama Cloud](media/visual-verification.png)
+
+## Команды CLI
+
+```bash
+/ollama status            # статус провайдера, квоты, модели
+/ollama usage             # окна расходов и статистика по моделям
+/ollama balance           # баланс кредитов
+/ollama accounts          # список аккаунтов и их расход
+/ollama models            # каталог моделей и параметры
+/ollama rules             # правила модель ➔ аккаунт
+/ollama test [model]      # проверочный запрос к модели
+```
+
+## Проверенные факты API (2026-10-21)
+
+- `GET https://ollama.com/v1/models` возвращает стандартный `data[]` и расширенный массив `models[]` с метаданными контекста и модальностей.
+- `GET https://ollama.com/api/tags` служит источником флагов `capabilities` по моделям.
+- Нативный `/api/chat` передает NDJSON с подробной статистикой токенов в финальном объекте.
+- Совместимый эндпоинт OpenAI `/v1/chat/completions` поддерживает стриминг, инструменты, зрение (vision) и `reasoning_effort`.
+
+## Ограничения
+
+- Только Ollama Cloud; локальный сервис `http://localhost:11434` данным плагином не регистрируется.
+- Эмбеддинги (embeddings) в облачном API не предоставляются.
+- Файловые вложения передаются текстовыми дескрипторами (handle), а не бинарными байтами.
+- Интерфейс требует web-профиль; в терминальном TUI доступны команда `/ollama` и маршрут модели.
+
+## Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY). См. [LICENSE](./LICENSE) и [NOTICE](./NOTICE).