nodmix 2026.5.25

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

@@ -0,0 +1,202 @@
+---
+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"
+---
+
+This doc lists **features that can invoke API keys** and where their costs show up. It focuses on
+Nodmix 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, Nodmix reads usage from
+  `stats`, normalizes `stats.cached` into `cacheRead`, and derives input tokens
+  from `stats.input_tokens - stats.cached` when needed.
+
+Anthropic note: Anthropic staff told us Nodmix-style Claude CLI usage is
+allowed again, so Nodmix treats Claude CLI reuse and `claude -p` usage as
+sanctioned for this integration unless Anthropic publishes a new policy.
+Anthropic still does not expose a per-message dollar estimate that Nodmix can
+show in `/usage full`.
+
+**CLI usage windows (provider quotas)**
+
+- `nodmix status --usage` and `nodmix 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 Nodmix inverts them before display. Count-based fields still win
+  when present. If the provider returns `model_remains`, Nodmix 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 Nodmix 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
+
+Nodmix 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
+Nodmix's local UI, such as **OpenAI Codex**, **Alibaba Cloud Model Studio
+Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, and
+Anthropic's Nodmix 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 / DeepInfra / Google / Mistral.
+- Image: OpenAI / OpenRouter / Anthropic / DeepInfra / 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 / DeepInfra / fal / MiniMax
+- Video generation: DeepInfra / 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 = "deepinfra"` → DeepInfra embeddings
+- `memorySearch.provider = "lmstudio"` → LM Studio embeddings (local/self-hosted)
+- `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 for a reachable signed-in local Ollama host; direct `https://ollama.com` search uses `OLLAMA_API_KEY`, and auth-protected hosts can reuse normal Ollama provider bearer auth
+- **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 plus the bundled `web-readability` plugin (no paid API). Disable `plugins.entries.web-readability.enabled` to skip local Readability extraction.
+
+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:
+
+- `nodmix status --usage`
+- `nodmix 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
+
+`nodmix 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).
+
+## Related
+
+- [Token use and costs](/reference/token-use)
+- [Prompt caching](/reference/prompt-caching)
+- [Usage tracking](/concepts/usage-tracking)

package/docs/reference/application-modernization-plan.md

@@ -0,0 +1,208 @@
+---
+summary: "Comprehensive application modernization plan with frontend delivery skill updates"
+title: "Application modernization plan"
+read_when:
+  - Planning a broad Nodmix application modernization pass
+  - Updating frontend implementation standards for app or Control UI work
+  - Turning a broad product quality review into phased engineering work
+---
+
+## Goal
+
+Move the application toward a cleaner, faster, more maintainable product without
+breaking current workflows or hiding risk in broad refactors. The work should
+land as small, reviewable slices with proof for each touched surface.
+
+## Principles
+
+- Preserve current architecture unless a boundary is demonstrably causing churn,
+  performance cost, or user-visible bugs.
+- Prefer the smallest correct patch for each issue, then repeat.
+- Separate required fixes from optional polish so maintainers can land high
+  value work without waiting on subjective decisions.
+- Keep plugin-facing behavior documented and backwards compatible.
+- Verify shipped behavior, dependency contracts, and tests before claiming a
+  regression is fixed.
+- Make the main user path better first: onboarding, auth, chat, provider setup,
+  plugin management, and diagnostics.
+
+## Phase 1: Baseline audit
+
+Inventory the current application before changing it.
+
+- Identify the top user workflows and the code surfaces that own them.
+- List dead affordances, duplicate settings, unclear error states, and expensive
+  render paths.
+- Capture current validation commands for each surface.
+- Mark issues as required, recommended, or optional.
+- Document known blockers that need owner review, especially API, security,
+  release, and plugin contract changes.
+
+Definition of done:
+
+- One issue list with repo-root file references.
+- Each issue has severity, owner surface, expected user impact, and a proposed
+  validation path.
+- No speculative cleanup items are mixed into required fixes.
+
+## Phase 2: Product and UX cleanup
+
+Prioritize visible workflows and remove confusion.
+
+- Tighten onboarding copy and empty states around model auth, gateway status,
+  and plugin setup.
+- Remove or disable dead affordances where no action is possible.
+- Keep important actions visible across responsive widths instead of hiding them
+  behind fragile layout assumptions.
+- Consolidate repeated status language so errors have one source of truth.
+- Add progressive disclosure for advanced settings while keeping core setup fast.
+
+Recommended validation:
+
+- Manual happy path for first-run setup and existing user startup.
+- Focused tests for any routing, config persistence, or status derivation logic.
+- Browser screenshots for changed responsive surfaces.
+
+## Phase 3: Frontend architecture tightening
+
+Improve maintainability without a broad rewrite.
+
+- Move repeated UI state transformations into narrow typed helpers.
+- Keep data fetching, persistence, and presentation responsibilities separate.
+- Prefer existing hooks, stores, and component patterns over new abstractions.
+- Split oversized components only when it reduces coupling or clarifies tests.
+- Avoid introducing broad global state for local panel interactions.
+
+Required guardrails:
+
+- Do not change public behavior as a side effect of file splitting.
+- Keep accessibility behavior intact for menus, dialogs, tabs, and keyboard
+  navigation.
+- Verify that loading, empty, error, and optimistic states still render.
+
+## Phase 4: Performance and reliability
+
+Target measured pain rather than broad theoretical optimization.
+
+- Measure startup, route transition, large list, and chat transcript costs.
+- Replace repeated expensive derived data with memoized selectors or cached
+  helpers where profiling proves value.
+- Reduce avoidable network or filesystem scans on hot paths.
+- Keep deterministic ordering for prompt, registry, file, plugin, and network
+  inputs before model payload construction.
+- Add lightweight regression tests for hot helpers and contract boundaries.
+
+Definition of done:
+
+- Each performance change records baseline, expected impact, actual impact, and
+  remaining gap.
+- No perf patch lands solely on intuition when cheap measurement is available.
+
+## Phase 5: Type, contract, and test hardening
+
+Raise correctness at the boundary points users and plugin authors depend on.
+
+- Replace loose runtime strings with discriminated unions or closed code lists.
+- Validate external inputs with existing schema helpers or zod.
+- Add contract tests around plugin manifests, provider catalogs, gateway protocol
+  messages, and config migration behavior.
+- Keep compatibility paths in doctor or repair flows instead of startup-time
+  hidden migrations.
+- Avoid test-only coupling to plugin internals; use SDK facades and documented
+  barrels.
+
+Recommended validation:
+
+- `pnpm check:changed`
+- Targeted tests for every changed boundary.
+- `pnpm build` when lazy boundaries, packaging, or published surfaces change.
+
+## Phase 6: Documentation and release readiness
+
+Keep user-facing docs aligned with behavior.
+
+- Update docs with behavior, API, config, onboarding, or plugin changes.
+- Add changelog entries only for user-visible changes.
+- Keep plugin terminology user-facing; use internal package names only where
+  needed for contributors.
+- Confirm release and install instructions still match the current command
+  surface.
+
+Definition of done:
+
+- Relevant docs are updated in the same branch as behavior changes.
+- Generated docs or API drift checks pass when touched.
+- The handoff names any skipped validation and why it was skipped.
+
+## Recommended first slice
+
+Start with a scoped Control UI and onboarding pass:
+
+- Audit first-run setup, provider auth readiness, gateway status, and plugin
+  setup surfaces.
+- Remove dead actions and clarify failure states.
+- Add or update focused tests for status derivation and config persistence.
+- Run `pnpm check:changed`.
+
+This gives high user value with limited architecture risk.
+
+## Frontend skill update
+
+Use this section to update the frontend-focused `SKILL.md` supplied with the
+modernization task. If adopting this guidance as a repo-local Nodmix skill,
+create `.agents/skills/nodmix-frontend/SKILL.md` first, keep the frontmatter
+that belongs in that target skill, then add or replace the body guidance with
+the following content.
+
+```markdown
+# Frontend Delivery Standards
+
+Use this skill when implementing or reviewing user-facing React, Next.js,
+desktop webview, or app UI work.
+
+## Operating rules
+
+- Start from the existing product workflow and code conventions.
+- Prefer the smallest correct patch that improves the current user path.
+- Separate required fixes from optional polish in the handoff.
+- Do not build marketing pages when the request is for an application surface.
+- Keep actions visible and usable across supported viewport sizes.
+- Remove dead affordances instead of leaving controls that cannot act.
+- Preserve loading, empty, error, success, and permission states.
+- Use existing design-system components, hooks, stores, and icons before adding
+  new primitives.
+
+## Implementation checklist
+
+1. Identify the primary user task and the component or route that owns it.
+2. Read the local component patterns before editing.
+3. Patch the narrowest surface that solves the issue.
+4. Add responsive constraints for fixed-format controls, toolbars, grids, and
+   counters so text and hover states cannot resize the layout unexpectedly.
+5. Keep data loading, state derivation, and rendering responsibilities clear.
+6. Add tests when logic, persistence, routing, permissions, or shared helpers
+   change.
+7. Verify the main happy path and the most relevant edge case.
+
+## Visual quality gates
+
+- Text must fit inside its container on mobile and desktop.
+- Toolbars may wrap, but controls must remain reachable.
+- Buttons should use familiar icons when the icon is clearer than text.
+- Cards should be used for repeated items, modals, and framed tools, not for
+  every page section.
+- Avoid one-note color palettes and decorative backgrounds that compete with
+  operational content.
+- Dense product surfaces should optimize for scanning, comparison, and repeated
+  use.
+
+## Handoff format
+
+Report:
+
+- What changed.
+- What user behavior changed.
+- Required validation that passed.
+- Any validation skipped and the concrete reason.
+- Optional follow-up work, clearly separated from required fixes.
+```