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

97 lines
6.2 KiB
Markdown

# 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](https://docs.openclaw.ai/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](https://opencode.ai/v2/docs/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](https://hermes-agent.nousresearch.com/docs/) | 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.