fengming 0.3.10 → 0.3.12

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

@@ -1,208 +0,0 @@
----
-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
-FengMing 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 FengMing has usage metadata and local pricing for the active model,
-  `/status` also shows **estimated cost** for the last reply. This can include
-  explicitly priced non-API-key providers such as Bedrock `aws-sdk` models.
-- 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**
-  when local pricing is configured for the active model and usage metadata is
-  available.
-- `/usage tokens` shows tokens only; subscription-style OAuth/token and CLI flows
-  still show tokens only unless that runtime supplies compatible usage metadata
-  and an explicit local price is configured.
-- Gemini CLI note: when the CLI returns JSON output, FengMing 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 FengMing-style Claude CLI usage is
-allowed again, so FengMing 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 FengMing can
-show in `/usage full`.
-
-**CLI usage windows (provider quotas)**
-
-- `fengming status --usage` and `fengming 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 FengMing inverts them before display. Count-based fields still win
-  when present. If the provider returns `model_remains`, FengMing 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 FengMing 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
-
-FengMing 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
-FengMing's local UI, such as **OpenAI Codex**, **Alibaba Cloud Model Studio
-Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, and
-Anthropic's FengMing 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 OAuth profile, `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:
-
-- `fengming status --usage`
-- `fengming 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
-
-`fengming 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

@@ -1,208 +0,0 @@
----
-summary: "Comprehensive application modernization plan with frontend delivery skill updates"
-title: "Application modernization plan"
-read_when:
-  - Planning a broad FengMing 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 FengMing skill,
-create `.agents/skills/fengming-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.
-```