Skip to content

docs: backfill source-vs-doc gaps (providers / channels — config / API / CLI to follow)#3201

Merged
houko merged 14 commits into
mainfrom
docs/source-gap-fill
Apr 26, 2026
Merged

docs: backfill source-vs-doc gaps (providers / channels — config / API / CLI to follow)#3201
houko merged 14 commits into
mainfrom
docs/source-gap-fill

Conversation

@houko

@houko houko commented Apr 26, 2026

Copy link
Copy Markdown
Contributor

Summary

After merging #3189 (docs catch-up wave) we ran 6 source-vs-docs scans and found gaps the docs still didn't cover. This is the rolling PR that fills those gaps. Single PR by request — more commits will be added on top.

So far in this PR:

  • 8 LLM providers added: Moonshot (Kimi), ChatGPT (session token), Kimi Coding, Qianfan (Baidu), VolcEngine (Doubao), Zhipu (GLM), Zhipu Coding (CodeGeex), Z.ai. Routed to hosted / tools / platforms based on driver type.
  • Cross-provider capability matrix on the providers index page (vision / tools / embeddings / file upload / prompt cache / image gen / audio for 28+ providers).
  • Bedrock dedup — the stale SigV4-style entry on platforms is removed; the current bearer-token driver stays on hosted. A pointer note on platforms directs readers to the right page.
  • Per-adapter channel notes — Slack SLACK_REACTIONS, WhatsApp send_voice + bot_phone/bot_name/group_trigger_patterns, Signal plain-text default + media attachment types, Feishu Typing reaction + @mention preservation. Each cross-references the consolidated detail block in integrations/channels.

Both EN and zh updated in lockstep (every change has its mirror).

Still to land in this PR (will push as follow-up commits):

  • 13 undocumented config sections + 36 top-level fields
  • New agent/tools page covering browser / process / schedule / cron / knowledge / media / a2a tool families + tool_search/tool_load meta-tools + apply_patch.move_to + skill_evolve_patch fuzzy matcher
  • 37 verified API endpoints currently absent from integrations/api/*
  • 31 verified CLI commands absent from integrations/cli/commands

Test plan

  • Build the docs site locally; click through /configuration/providers/* and confirm every new provider section renders with its env var + setup steps + minimal config.toml
  • Open the capability matrix on /configuration/providers and check rows align across screen widths
  • On /integrations/channels/core confirm the new Slack/WhatsApp/Signal subsections deep-link into the overview's anchor IDs
  • Same for /integrations/channels/enterprise (Feishu)
  • Repeat all of the above on the zh side

houko added 2 commits April 26, 2026 09:43
…x, per-adapter notes

Providers:
- hosted: add Moonshot (Kimi)
- tools: add ChatGPT (session token), Kimi Coding (Anthropic Messages compat)
- platforms: add Qianfan / VolcEngine / Zhipu / Zhipu-Coding / Z.ai
- platforms: drop stale SigV4-style Bedrock entry (current driver is bearer-token, documented in hosted)
- providers index: cross-provider capability matrix (vision / tools / embeddings / file upload / cache / image gen / audio)

Channels (cross-references to overview details):
- Slack: SLACK_REACTIONS env + processing-state behaviour
- WhatsApp: send_voice + bot_phone / bot_name / group_trigger_patterns
- Signal: plain-text default + media attachment type list
- Feishu: Typing reaction + @mention preservation
Same content as the EN commit, translated:
- hosted: Moonshot (Kimi)
- tools: ChatGPT (session), Kimi Coding
- platforms: Qianfan / VolcEngine / Zhipu / Zhipu-Coding / Z.ai
- platforms: drop stale SigV4 Bedrock entry (current driver moved to hosted)
- providers index: 能力矩阵 covering all 28+ providers
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@github-actions github-actions Bot added ready-for-review PR is ready for maintainer review no-rust-required This task does not require Rust knowledge area/docs Documentation and guides size/L 250-999 lines changed and removed no-rust-required This task does not require Rust knowledge labels Apr 26, 2026
houko added 2 commits April 26, 2026 09:46
…shboard auth

Adds previously-undocumented top-level fields and config sections to
configuration/core:

- [rate_limit] (8 fields, including the terminal WS budget rationale)
- [sanitize] (3 fields, prompt-injection block patterns)
- [privacy] (PII redact / pseudonymize)
- [telemetry] (OTLP + Prometheus, auto_start opt-in)
- [heartbeat] (autonomous-agent unresponsive detection)
- [compaction] (LLM-based summarisation thresholds)
- [tool_invoke] (REST tool-invocation allowlist)
- [parallel_tools] (extended — full field reference)
- Resource limits: max_upload_size_bytes, max_request_body_bytes,
  max_concurrent_bg_llm, max_agent_call_depth, local_probe_interval_secs,
  strict_config, update_channel, trusted_hosts, trusted_manifest_signers
- Dashboard auth: dashboard_user / dashboard_pass / dashboard_pass_hash /
  require_auth_for_reads
… dashboard auth

Same content as the EN core-config commit, translated. Covers
[rate_limit], [sanitize], [privacy], [telemetry], [heartbeat],
[compaction], [tool_invoke], [parallel_tools] (extended), top-level
resource limits, and dashboard authentication fields.
@github-actions github-actions Bot added no-rust-required This task does not require Rust knowledge size/XL 1000+ lines changed and removed size/L 250-999 lines changed labels Apr 26, 2026
houko and others added 10 commits April 26, 2026 09:49
Adds 37 endpoints across 13 groups to the endpoint summary table on
the API index page. All entries verified against server.rs / sub-router
files — no hallucinations. Groups:

- Plugins lifecycle (doctor / status / health / env / export / lint /
  enable / reload / sign / prewarm)
- Skills registry & runtime (skill detail / supporting file / registry
  / reload)
- Tool invoke endpoint (POST /api/tools/{name}/invoke)
- Terminal (health + WebSocket)
- A2A extended task API (GET task / POST tasks/send)
- MCP HTTP transport
- Config & registry (export / schema / wildcard model lookup / template TOML)
- Goals & inbox (goal templates / inbox status / sessions search)
- Approvals extended (audit / count / batch)
- Auto-dream status
- Hands lifecycle (DELETE / reload)
- Media transcribe
- ClawHub CN mirror (browse / search)
- Init wizard

Both EN and zh updated.
…mands)

Adds a "Top-Level Command Reference" section to integrations/cli/commands
listing every top-level command verified against
crates/librefang-cli/src/main.rs:

- Daemon lifecycle (start, stop, restart, health, status, logs, tui)
- Setup / onboarding / migration (onboard, setup, configure, migrate,
  reset, uninstall)
- Catalog & registry (models, mcp, webhooks, sessions, memory, cron,
  approvals)
- Security / auth / vault (vault, auth chatgpt, security, devices, qr,
  hash-password)
- Agent shortcuts (spawn, agents, kill, message — aliases of nested forms)
- Scaffolding (new skill, new mcp)
- Extra `hand` subcommands (status, active, settings, set, reload, chat)
- System & meta (system info / version, gateway)
- Slash commands not in the original table: /reboot, /compact, /think

Both EN and zh updated.
Documents tool families that previously lived only in source code:
- Meta-tools: tool_search / tool_load (the lazy_tools mechanism)
- A2A: a2a_discover / a2a_send (cross-instance agent messaging)
- Browser: 8 Playwright-backed tools (navigate, click, type, scroll,
  wait, screenshot, run_js, close)
- Process lifecycle: 5 subprocess tools (start, write, list, poll, kill)
- Runtime scheduling: 6 tools (schedule_create/list/delete + cron_create/
  list/cancel) — distinct from manifest [[cron]]
- Knowledge graph: 3 tools (add_entity / add_relation / query)
- Media: 10+ tools (image / vision / TTS / STT / music / video / canvas)
- notify_owner (private notice that bypasses chat history)
- Geolocation, docker_exec, skill_read_file
- apply_patch move_to semantics
- skill_evolve_patch 5-strategy fuzzy matcher

Plus matching nav entries in EN and zh navigation.
1. Config (5 sections + 5 fields, EN+zh):
   - [skills], [notification], [triggers], [task_board], [registry], [azure_openai]
   - top-level: log_dir, config_version, qwen_code_path, provider_proxy_urls

2. Provider dead-link cleanup (EN+zh):
   - Remove Voyage AI / Anyscale from platforms — verified no driver, no env
     wiring, no model catalog entry exist
   - Remove AI21 Labs from hosted — only AI21_API_KEY reference is in
     CLI strip lists, no actual driver
   - Update embedding auto-detect ladder in providers/local to match
     the real detect_embedding_provider source: OPENAI / OPENROUTER /
     MISTRAL / TOGETHER / FIREWORKS / COHERE + Ollama / vLLM / LMStudio
   - Drop ghost entries from providers/index TOC

3. Plugin transform_tool_result hook expanded (EN+zh):
   - Trait signature, HookContext fields, request/response shapes
   - Loop position, first-wins sequential semantics, fail-open
   - Use cases, panic semantics, no transform-side cap

4. Proactive memory subsystem expanded (EN+zh):
   - Entry schema (12 fields)
   - Scopes (user/session/agent), categories, decay formula
   - Auto-consolidation trigger and similarity ladder
   - Per-agent isolation guarantees and 1000-cap eviction
   - Corrected API endpoint list (the old /api/memory/proactive/* never
     shipped; real endpoints are /api/memory and /api/memory/agents/{id}/*)
1. Webhook adapter page now cross-references the deliver_only mode
   (was only described on the channels overview, easy to miss when
   reading the per-adapter section).
2. Telegram adapter page now cross-references Channel File Downloads
   (Telegram is the most common source of file attachments; users
   reading the Telegram section had no path to the download config).
3. Drop ghost /api/memory/kg/* endpoints from agent/memory — these
   never shipped. Replace with the real per-agent endpoints
   (/api/memory/agents/{id}/relations) and a pointer to the in-loop
   knowledge_* tools.
4. Add `librefang config unset <KEY>` to the CLI config commands —
   confirmed against main.rs:2119. Distinct from `config delete-key`
   which removes a provider API key from .env.

Both EN and zh updated.
Three deep-scan agents cross-validated the entire codebase against
docs and found a final batch of real gaps. All findings verified
against source before writing.

Config (configuration/core, EN+zh):
  Add an "Additional config sections (appendix)" listing 13
  KernelConfig top-level sections that exist in code but had no doc
  entry: tool_timeout_secs / [tool_timeouts], [[fallback_providers]],
  [[mcp_servers]], [webhook_triggers], [extensions], [reload],
  [auto_reply], [broadcast], [canvas], [a2a], [pairing], [exec_policy].

Agent manifest (agent/templates, EN+zh):
  Add "Agent Manifest Field Reference" — 16 fields previously absent
  from docs:
  - tool scoping: tool_allowlist, tool_blocklist, tools_disabled,
    allowed_plugins, mcp_servers, skills_disabled
  - identity: generate_identity_files, inherit_parent_context,
    auto_evolve, is_hand, pinned_model
  - per-agent overrides: [channel_overrides], [exec_policy]
  - response shaping: show_progress, response_format,
    web_search_augmentation, [[context_injection]]

Built-in tools (agent/tools, EN+zh):
  Add 22 tools to the reference page, covering families that were
  entirely missing:
  - Same-daemon inter-agent: agent_send, agent_spawn, agent_list,
    agent_find, agent_kill, goal_update
  - Memory (per-agent): memory_store, memory_recall, memory_list
  - Task queue: task_post, task_claim, task_complete, task_list
  - Channel: channel_send
  - Workflow / event: workflow_run, event_publish, system_time
  - Skill evolution (extended): skill_evolve_create, _update, _delete,
    _rollback, _write_file, _remove_file
  - Browser additions: browser_back, browser_read_page

API endpoints (integrations/api, EN+zh):
  Add 16 endpoints verified in server.rs / routes/prompts.rs:
  - Dashboard auth: POST /auth/logout
  - API meta: GET /api/versions, /api/profiles, /api/profiles/{name}
  - Prompt versioning & A/B testing surface (12 endpoints under
    /agents/{agent_id}/prompts/* and /prompts/*) — the
    [prompt_intelligence] feature
Round 3 inadvertently added /api/versions and /api/profiles{,/{name}}
to the new "API meta / introspection" section even though they were
already in the System group at the top of the table. Drop the dupes
from both EN and zh; /auth/logout stays since it's genuinely new.
…/api/approvals/totp/revoke

Narrow per-endpoint verification of all 341 documented endpoints
against server.rs / routes/*.rs found exactly one real mismatch:
the docs claimed DELETE /api/approvals/totp but the actual route
registered in routes/system.rs:90 is POST /api/approvals/totp/revoke.

(The earlier verify-agent's broad-sweep claim of "72 missing
endpoints" was 71 false positives — the agent failed to search
oauth.rs, routes/system.rs and routes/skills.rs and got tripped
up by axum {name} vs documented {id} param naming. Manual grep
confirmed 340 of 341 entries are real.)

The librefang main repo's CLAUDE.md has the same stale entry on
line 122 — fixing that needs a separate PR against the main repo.

Both EN and zh updated.
@houko
houko merged commit 1bdf72d into main Apr 26, 2026
13 of 14 checks passed
@houko
houko deleted the docs/source-gap-fill branch April 26, 2026 01:33
@github-actions github-actions Bot removed the ready-for-review PR is ready for maintainer review label Apr 26, 2026
houko added a commit that referenced this pull request Apr 26, 2026
The HTML comment broke the docs deploy on main (#3201) — MDX v3 doesn't
accept `<!-- ... -->` and the parser chokes on `!`:

  page.mdx:67:2: Unexpected character `!` (U+0021) before name

The note was a TODO for the next maintainer dressed up as documentation.
Git history already records why those providers aren't listed; the
rendered docs page doesn't need to carry the explanation forever, and
removing it instead of porting to MDX comment syntax avoids leaving an
attractive nuisance for similar non-rendered annotations.
houko added a commit that referenced this pull request Apr 26, 2026
The HTML comment broke the docs deploy on main (#3201) — MDX v3 doesn't
accept `<!-- ... -->` and the parser chokes on `!`:

  page.mdx:67:2: Unexpected character `!` (U+0021) before name

The note was a TODO for the next maintainer dressed up as documentation.
Git history already records why those providers aren't listed; the
rendered docs page doesn't need to carry the explanation forever, and
removing it instead of porting to MDX comment syntax avoids leaving an
attractive nuisance for similar non-rendered annotations.
@houko houko mentioned this pull request Apr 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs Documentation and guides no-rust-required This task does not require Rust knowledge size/XL 1000+ lines changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant