durar-ai 2026.4.4

package/docs/reference/api-usage-costs.md

@@ -0,0 +1,198 @@
+---
+summary: "Audit what can spend money, which keys are used, and how to view usage"
+read_when:
+  - You want to understand which features may call paid APIs
+  - You need to audit keys, costs, and usage visibility
+  - You’re explaining /status or /usage cost reporting
+title: "API Usage and Costs"
+---
+
+# API usage & costs
+
+This doc lists **features that can invoke API keys** and where their costs show up. It focuses on
+Durar features that can generate provider usage or paid API calls.
+
+## Where costs show up (chat + CLI)
+
+**Per-session cost snapshot**
+
+- `/status` shows the current session model, context usage, and last response tokens.
+- If the model uses **API-key auth**, `/status` also shows **estimated cost** for the last reply.
+- If live session metadata is sparse, `/status` can recover token/cache
+  counters and the active runtime model label from the latest transcript usage
+  entry. Existing nonzero live values still take precedence, and prompt-sized
+  transcript totals can win when stored totals are missing or smaller.
+
+**Per-message cost footer**
+
+- `/usage full` appends a usage footer to every reply, including **estimated cost** (API-key only).
+- `/usage tokens` shows tokens only; subscription-style OAuth/token and CLI flows hide dollar cost.
+- Gemini CLI note: when the CLI returns JSON output, Durar reads usage from
+  `stats`, normalizes `stats.cached` into `cacheRead`, and derives input tokens
+  from `stats.input_tokens - stats.cached` when needed.
+
+Anthropic note: Anthropic's public Claude Code docs still include direct Claude
+Code terminal usage in Claude plan limits. Separately, Anthropic told Durar
+users that starting **April 4, 2026 at 12:00 PM PT / 8:00 PM BST**, the
+**Durar** Claude-login path counts as third-party harness usage and
+requires **Extra Usage** billed separately from the subscription. Anthropic
+does not expose a per-message dollar estimate that Durar can show in
+`/usage full`.
+
+**CLI usage windows (provider quotas)**
+
+- `Durar status --usage` and `Durar channels list` show provider **usage windows**
+  (quota snapshots, not per-message costs).
+- Human output is normalized to `X% left` across providers.
+- Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI,
+  OpenAI Codex, MiniMax, Xiaomi, and z.ai.
+- MiniMax note: its raw `usage_percent` / `usagePercent` fields mean remaining
+  quota, so Durar inverts them before display. Count-based fields still win
+  when present. If the provider returns `model_remains`, Durar prefers the
+  chat-model entry, derives the window label from timestamps when needed, and
+  includes the model name in the plan label.
+- Usage auth for those quota windows comes from provider-specific hooks when
+  available; otherwise Durar falls back to matching OAuth/API-key
+  credentials from auth profiles, env, or config.
+
+See [Token use & costs](/reference/token-use) for details and examples.
+
+## How keys are discovered
+
+Durar can pick up credentials from:
+
+- **Auth profiles** (per-agent, stored in `auth-profiles.json`).
+- **Environment variables** (e.g. `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`).
+- **Config** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`,
+  `plugins.entries.firecrawl.config.webFetch.apiKey`, `memorySearch.*`,
+  `talk.providers.*.apiKey`).
+- **Skills** (`skills.entries.<name>.apiKey`) which may export keys to the skill process env.
+
+## Features that can spend keys
+
+### 1) Core model responses (chat + tools)
+
+Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the
+primary source of usage and cost.
+
+This also includes subscription-style hosted providers that still bill outside
+Durar's local UI, such as **OpenAI Codex**, **Alibaba Cloud Model Studio
+Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, and
+Anthropic's Durar Claude-login path with **Extra Usage** enabled.
+
+See [Models](/providers/models) for pricing config and [Token use & costs](/reference/token-use) for display.
+
+### 2) Media understanding (audio/image/video)
+
+Inbound media can be summarized/transcribed before the reply runs. This uses model/provider APIs.
+
+- Audio: OpenAI / Groq / Deepgram / Google / Mistral.
+- Image: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI.
+- Video: Google / Qwen / Moonshot.
+
+See [Media understanding](/nodes/media-understanding).
+
+### 3) Image and video generation
+
+Shared generation capabilities can also spend provider keys:
+
+- Image generation: OpenAI / Google / fal / MiniMax
+- Video generation: Qwen
+
+Image generation can infer an auth-backed provider default when
+`agents.defaults.imageGenerationModel` is unset. Video generation currently
+requires an explicit `agents.defaults.videoGenerationModel` such as
+`qwen/wan2.6-t2v`.
+
+See [Image generation](/tools/image-generation), [Qwen Cloud](/providers/qwen),
+and [Models](/concepts/models).
+
+### 4) Memory embeddings + semantic search
+
+Semantic memory search uses **embedding APIs** when configured for remote providers:
+
+- `memorySearch.provider = "openai"` → OpenAI embeddings
+- `memorySearch.provider = "gemini"` → Gemini embeddings
+- `memorySearch.provider = "voyage"` → Voyage embeddings
+- `memorySearch.provider = "mistral"` → Mistral embeddings
+- `memorySearch.provider = "ollama"` → Ollama embeddings (local/self-hosted; typically no hosted API billing)
+- Optional fallback to a remote provider if local embeddings fail
+
+You can keep it local with `memorySearch.provider = "local"` (no API usage).
+
+See [Memory](/concepts/memory).
+
+### 5) Web search tool
+
+`web_search` may incur usage charges depending on your provider:
+
+- **Brave Search API**: `BRAVE_API_KEY` or `plugins.entries.brave.config.webSearch.apiKey`
+- **Exa**: `EXA_API_KEY` or `plugins.entries.exa.config.webSearch.apiKey`
+- **Firecrawl**: `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webSearch.apiKey`
+- **Gemini (Google Search)**: `GEMINI_API_KEY` or `plugins.entries.google.config.webSearch.apiKey`
+- **Grok (xAI)**: `XAI_API_KEY` or `plugins.entries.xai.config.webSearch.apiKey`
+- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `plugins.entries.moonshot.config.webSearch.apiKey`
+- **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY`, or `plugins.entries.minimax.config.webSearch.apiKey`
+- **Ollama Web Search**: key-free by default, but requires a reachable Ollama host plus `ollama signin`; can also reuse normal Ollama provider bearer auth when the host requires it
+- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `plugins.entries.perplexity.config.webSearch.apiKey`
+- **Tavily**: `TAVILY_API_KEY` or `plugins.entries.tavily.config.webSearch.apiKey`
+- **DuckDuckGo**: key-free fallback (no API billing, but unofficial and HTML-based)
+- **SearXNG**: `SEARXNG_BASE_URL` or `plugins.entries.searxng.config.webSearch.baseUrl` (key-free/self-hosted; no hosted API billing)
+
+Legacy `tools.web.search.*` provider paths still load through the temporary compatibility shim, but they are no longer the recommended config surface.
+
+**Brave Search free credit:** Each Brave plan includes \$5/month in renewing
+free credit. The Search plan costs \$5 per 1,000 requests, so the credit covers
+1,000 requests/month at no charge. Set your usage limit in the Brave dashboard
+to avoid unexpected charges.
+
+See [Web tools](/tools/web).
+
+### 5) Web fetch tool (Firecrawl)
+
+`web_fetch` can call **Firecrawl** when an API key is present:
+
+- `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webFetch.apiKey`
+
+If Firecrawl isn’t configured, the tool falls back to direct fetch + readability (no paid API).
+
+See [Web tools](/tools/web).
+
+### 6) Provider usage snapshots (status/health)
+
+Some status commands call **provider usage endpoints** to display quota windows or auth health.
+These are typically low-volume calls but still hit provider APIs:
+
+- `Durar status --usage`
+- `Durar models status --json`
+
+See [Models CLI](/cli/models).
+
+### 7) Compaction safeguard summarization
+
+The compaction safeguard can summarize session history using the **current model**, which
+invokes provider APIs when it runs.
+
+See [Session management + compaction](/reference/session-management-compaction).
+
+### 8) Model scan / probe
+
+`Durar models scan` can probe OpenRouter models and uses `OPENROUTER_API_KEY` when
+probing is enabled.
+
+See [Models CLI](/cli/models).
+
+### 9) Talk (speech)
+
+Talk mode can invoke **ElevenLabs** when configured:
+
+- `ELEVENLABS_API_KEY` or `talk.providers.elevenlabs.apiKey`
+
+See [Talk mode](/nodes/talk).
+
+### 10) Skills (third-party APIs)
+
+Skills can store `apiKey` in `skills.entries.<name>.apiKey`. If a skill uses that key for external
+APIs, it can incur costs according to the skill’s provider.
+
+See [Skills](/tools/skills).

package/docs/reference/credits.md

@@ -0,0 +1,30 @@
+---
+summary: "Project origin, contributors, and license."
+read_when:
+  - You want the project backstory or contributor credits
+title: "Credits"
+---
+
+# Credits and Acknowledgments
+
+## The name
+
+Durar = CLAW + TARDIS, because every space lobster needs a time and space machine.
+
+## Credits
+
+- **Peter Steinberger** ([@steipete](https://x.com/steipete)) - Creator, lobster whisperer
+- **Mario Zechner** ([@badlogicc](https://x.com/badlogicgames)) - Pi creator, security pen tester
+- **Clawd** - The space lobster who demanded a better name
+
+## Core contributors
+
+- **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com)) - Blogwatcher skill
+- **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com)) - Location parsing (Telegram and WhatsApp)
+- **Vincent Koc** ([@vincentkoc](https://github.com/vincentkoc), [@vincent_koc](https://x.com/vincent_koc)) - Agents, Telemetry, Hooks, Security
+
+## License
+
+MIT - Free as a lobster in the ocean.
+
+> "We are all just playing with our own prompts." (An AI, probably high on tokens)

package/docs/reference/device-models.md

@@ -0,0 +1,47 @@
+---
+summary: "How Durar vendors Apple device model identifiers for friendly names in the macOS app."
+read_when:
+  - Updating device model identifier mappings or NOTICE/license files
+  - Changing how Instances UI displays device names
+title: "Device Model Database"
+---
+
+# Device model database (friendly names)
+
+The macOS companion app shows friendly Apple device model names in the **Instances** UI by mapping Apple model identifiers (e.g. `iPad16,6`, `Mac16,6`) to human-readable names.
+
+The mapping is vendored as JSON under:
+
+- `apps/macos/Sources/Durar/Resources/DeviceModels/`
+
+## Data source
+
+We currently vendor the mapping from the MIT-licensed repository:
+
+- `kyle-seongwoo-jun/apple-device-identifiers`
+
+To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/Durar/Resources/DeviceModels/NOTICE.md`).
+
+## Updating the database
+
+1. Pick the upstream commits you want to pin to (one for iOS, one for macOS).
+2. Update the commit hashes in `apps/macos/Sources/Durar/Resources/DeviceModels/NOTICE.md`.
+3. Re-download the JSON files, pinned to those commits:
+
+```bash
+IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
+MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
+  -o apps/macos/Sources/Durar/Resources/DeviceModels/ios-device-identifiers.json
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
+  -o apps/macos/Sources/Durar/Resources/DeviceModels/mac-device-identifiers.json
+```
+
+4. Ensure `apps/macos/Sources/Durar/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
+5. Verify the macOS app builds cleanly (no warnings):
+
+```bash
+swift build --package-path apps/macos
+```