Skip to content

docs: fix outdated and incorrect references#2618

Open
dgageot wants to merge 1 commit intodocker:mainfrom
dgageot:docs/fix-outdated-and-missing
Open

docs: fix outdated and incorrect references#2618
dgageot wants to merge 1 commit intodocker:mainfrom
dgageot:docs/fix-outdated-and-missing

Conversation

@dgageot
Copy link
Copy Markdown
Member

@dgageot dgageot commented May 4, 2026

A handful of doc pages had drifted away from the code. This PR realigns them with the current behavior. No code changes — docs only.

What's fixed

File Issue Fix
docs/tools/tasks/index.md Tasks tool was documented with the wrong storage backend, default path, and tool names The tasks tool stores tasks in a JSON file (not SQLite), defaults to ./tasks.json relative to the config dir (not ~/.cagent/tasks.db), and exposes create_task / get_task / update_task / delete_task / list_tasks / next_task / add_dependency / remove_dependency. The old doc only listed four tools and the wrong name add_task (vs. actual create_task). Also documents priorities and dependencies.
docs/providers/openai/index.md Mentioned a non-existent --gateway CLI flag The WebSocket transport falls back to SSE when --models-gateway is set (the actual flag, defined in cmd/root/flags.go).
docs/configuration/models/index.md temperature range listed as 0.0–1.0; frequency_penalty and presence_penalty listed as 0.0–2.0; provider list cut off mid-sentence temperature is provider-dependent up to 0.0–2.0 (Anthropic caps at 1.0); penalties run -2.0–2.0; the provider row now lists every alias from pkg/model/provider/aliases.go plus a pointer to named providers. The values now match what docs/providers/custom/index.md already says.
docs/configuration/agents/index.md Properties Reference table listed a top-level rag: field on agents Agents don't have a rag field. RAG is attached through toolsets: - type: rag, ref: <name> (see examples/rag.yaml). Row removed; the schema/example block already mentioned the correct way.
docs/community/troubleshooting/index.md "The path field is only valid for memory toolsets" path is also valid on the tasks toolset and on the agent-level cache block (per the Path field on Toolset / CacheConfig in pkg/config/latest/types.go).
docs/features/rag/index.md The chunked-embeddings strategy was shown with a model: field The actual field is embedding_model: — matches every example under examples/rag/*.yaml and the parameter name read by pkg/rag/strategy/chunked_embeddings.go. Fixed in three code blocks and the reference table.

Verification

  • temperature / top_p / penalty ranges cross-checked with docs/providers/custom/index.md (which already had the correct ranges) and OpenAI's API reference.
  • Tasks tool surface verified against pkg/tools/builtin/tasks.go (registered tool names) and pkg/teamloader/registry.go (default path = tasks.json).
  • --models-gateway flag verified in cmd/root/flags.go.
  • embedding_model field verified in pkg/rag/strategy/chunked_embeddings.go and examples/rag/{hybrid,custom_provider,reranking,semantic_embeddings}.yaml.
  • RAG-via-toolset usage confirmed in examples/rag.yaml.

A handful of doc pages drifted away from the code. This sweep
realigns them with the current behavior:

- tools/tasks: the tasks tool stores tasks in a JSON file (not
  SQLite), defaults to ./tasks.json (not ~/.cagent/tasks.db),
  and exposes create_task / get_task / update_task / delete_task /
  list_tasks / next_task / add_dependency / remove_dependency
  (the old doc only listed four tools and the wrong name
  add_task).
- providers/openai: the WebSocket transport falls back to SSE
  when --models-gateway is set, not the non-existent --gateway
  flag.
- configuration/models: temperature is provider-dependent up to
  2.0 (Anthropic caps at 1.0); frequency_penalty and
  presence_penalty go from -2.0 to 2.0, not 0.0 to 2.0; the
  provider list now matches model/provider/aliases.go.
- configuration/agents: drop the bogus 'rag' agent property —
  RAG is wired up via toolsets: - type: rag, ref: <name>,
  not via a top-level field on the agent.
- community/troubleshooting: 'path' is also valid for the
  tasks toolset and for the agent-level cache block, not just
  memory.
- features/rag: the chunked-embeddings strategy field is
  'embedding_model' (matching examples/rag/*.yaml and
  pkg/rag/strategy/chunked_embeddings.go), not 'model'.

Assisted-By: docker-agent
@dgageot dgageot requested a review from a team as a code owner May 4, 2026 04:13
@docker-agent
Copy link
Copy Markdown

docker-agent Bot commented May 4, 2026

PR Review Failed — The review agent encountered an error and could not complete the review. View logs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant