Raven-1/docs/documentation-references.md
userName20260323 8a1ebdc577
docs: organize bilingual documentation navigation (#635)
## Summary

Reorganize the Raven documentation landing page and expand the bilingual
documentation site.

- Add bilingual guidance for agent collaboration, ACP and A2A protocols,
DAG orchestration, channels, browser collaboration, knowledge bases,
Playbooks, proactive follow-ups, Oncall, permissions, tracing,
trajectory replay, and Evolver.
- Group daily usage under `Use Raven` and `Using Raven`.
- Group `Technical Reference` and `Developer Guide` under `Explore the
documentation` while preserving separate cards.

## Type

- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- [x] Relevant tests pass locally
- [ ] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

Exact checks:

- `uv run --frozen --group docs mkdocs build -f docs-site/mkdocs.yml
--strict` - passed.
- `uv run --frozen --group docs pytest tests/test_docs_site.py
tests/test_living_docs.py
tests/integration/test_docs_site_controls_e2e.py -q -o addopts=''` - 77
passed.
- `uv run --frozen python scripts/check_commit_messages.py
origin/main..HEAD` - passed.
- `git diff --check origin/main...HEAD` - passed.
- `make check-large-files` - passed.

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

This is a documentation-only change. It does not change runtime
behavior, configuration semantics, or public APIs. Reverting the
documentation commits restores the previous site content and navigation.

## Related Issues

N/A

---------

Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Claude (claude) <noreply@anthropic.com>
2026-09-22 16:14:44 +08:00

6.2 KiB

Documentation reference sources

The public guides under docs-site/docs/ describe Raven's current implementation, not feature parity with another product. The following documentation was consulted on 2026-09-22 to improve task-oriented navigation, setup examples, security explanations, and troubleshooting. These are design references, not dependencies.

Reference Approach adopted Raven-specific boundary
OpenClaw CLI docs Make documentation discovery explicit; distinguish installed CLI help from hosted documentation search Raven has site search and CLI help, not an openclaw docs-equivalent hosted search command
OpenCode V2 permissions Explain decision order, examples, approval scope, and the difference between permission and isolation Raven uses a tool-tier mapping and strictest matching specific exec rule, with * as fallback; it does not use V2's ordered action/resource/effect array
Hermes Agent documentation Organize skills, memory, MCP, messaging, operations, and developer extensions by user task Raven's retrieval, backend memory processing, and separate Evolver are distinct mechanisms; Hermes's self-improvement claims are not Raven guarantees

Implementation sources

  • ACP: raven/acp/capabilities.py, raven/acp/methods.py, raven/acp/replay.py, and raven/acp_client/permissions.py.
  • A2A: raven/a2a/card.py, raven/a2a/routes_aiohttp.py, raven/a2a/runtime.py, raven/a2a/executor.py, and raven/a2a_client/client.py.
  • DAG execution: raven/agent/subagent/dag_graph.py, raven/agent/subagent/dag_tool.py, raven/agent/subagent/dag_runner.py, and raven/agent/subagent/dag_resume.py.
  • Permission decisions: raven/permissions/gate.py, raven/permissions/rules.py, and raven/permissions/session.py.
  • Capability vocabulary: CONTEXT-MAP.md, CONTEXT.md, and agents/BUILDING.md.
  • Agent setup and presets: raven/agent/subagent/presets.py, raven/agent/subagent/acp_registry_presets.py, and raven/cli/agents_commands.py.
  • Messaging: raven/channels/registry.py, the adapter spec.py declarations, raven/cli/channel_commands.py, raven/channels/intake.py, raven/auth/allowlist.py, and raven/gateway/outlet.py.
  • Plugin development: raven/plugins/manifest.py, raven/plugins/context.py, raven/contracts/participant.py, and raven/contracts/subagent_backend.py.
  • Playbooks: raven/cli/playbook_commands.py, raven/playbook/types.py, store.py, validate.py, executor.py, params.py, credentials.py, and runtime.py in raven/playbook/. Creation is immediately usable; disabling affects model discovery, not explicit CLI runs. Stored parameter type declarations do not enforce runtime value types.
  • Evolver: evolver/README.md (including its planned-retirement notice), evolver/cli.py, evolver/launch/, benchmarks/appworld/evolve/entry.py, evolver/orchestrator/gates/pipeline.py, and evolver/orchestrator/sealed/runner.py. The launcher registers AppWorld; precheck can call the subject endpoint; navigation promotion is distinct from statistical credit, and finalization is distinct from pausing.

Navigation choices

The collaboration expansion adds task-oriented guides for sub-agent instances, Oncall campaigns, shared-browser work, knowledge retrieval, and trajectory debugging. Evolver's two existing URLs are grouped under usage/experiments and design/implementation. Proactivity retains separate Guide and Developers entries.

Additional implementation checks:

  • Direct chat and steering: raven/rpc/methods/instances.py, raven/agent/subagent/direct_chat.py, manager.py in the same directory, and ui-web/src/features/subagents/source.ts. The current WebUI instance composer sends ordinary turns; server steering is a separate RPC contract.
  • Dynamic workers: raven/agent/loop/wiring.py, raven/agent/subagent/delegate.py, charter.py, charter_code.py, and raven/playbook/agent_generator.py.
  • Oncall: agents/raven-oncall/subagent.json, its oncall-flow tools, wakes.py, and raven/cli/ops_connection_commands.py.
  • Browser: docs/browser-and-desktop.md, raven/browser/driver.py, policy.py, and ui-web/src/features/browser/. URL checks are not a complete network-isolation boundary.
  • Knowledge: raven/knowledge/_manager.py, _embedding.py, raven/rpc/methods/knowledge.py, and raven/rpc/models.py. The default parsers are text/structured text; the current WebUI source has backend fixtures and styling but no complete mounted knowledge-management feature.
  • Memory: raven/context_engine/factory.py, segments/curator.py, raven/memory_engine/store_pipeline.py, and plugins-dist/everos-memory/raven_everos/backend.py. The current host has no runtime consumer of the retained skillForge.extraction config despite older prose describing a local pipeline; the site no longer promises that enabling that field starts one.
  • Trajectories: raven/trajectory/replay.py, regression.py, raven/cli/trajectory_commands.py and trajectory_regression_commands.py.
  • Raven-Code: agents/raven-code/plugins/code-flow/raven-plugin.toml, code_flow/flow.py, manifest.py, sessions.py, and tools/.

The three audience groups remain Guide, Reference, and Developers. Daily-use, channel, and agent-setup pages belong in Guide; wire/runtime contracts belong in Reference; authoring agents, plugins, and adapters belongs in Developers. Existing page filenames are retained when moving their navigation entries.

The Hermes-style separation of usage, messaging, integrations, and extension development is an information-architecture reference, not a renaming of Raven's runtime layers. The architecture page maps surfaces to runtime, execution, and state ownership using Raven's own vocabulary.

Capability declarations and implementation tests take precedence over dated plans and stale CLI prose when describing support. In particular, ACP session modes and per-session stdio MCP are implemented despite older help text; DAG confirmation without an ask channel currently proceeds unconfirmed; A2A peer entries are credential mappings, not a network denylist.