userName20260323 e708f34a91
docs: align bilingual documentation with runtime behavior (#551)
## Summary

- Align English and Chinese documentation for Docker/Compose, sandbox
execution, and the in-tree tracing API with verified runtime behavior.
- Separate proactivity usage guidance from developer design and
implementation details, with configuration, troubleshooting, cost, and
safety boundaries.
- Update navigation and remove redundant section separators. Keep page
URLs unchanged.
- Preserve published proactivity section and title anchors in both
languages. Use native aliases for same-page content and visible
migration links for moved sections, with regression tests.
- Clarify Sentinel delivery fallback and menu-selection requirements,
tracing-on/off argument handling, headless CLI menu output, and viewer
descriptor lookup. Add focused regression coverage without changing
runtime behavior.
- Clarify the initial frozen baseline and improve Evolver wording in the
bilingual site and repository mapping. Keep its structure, navigation,
implementation terms, and technical claims unchanged; broader Evolver
documentation work is excluded.
- No runtime changes.

## Type

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

## Verification

Passed on the rebased revision:

```bash
uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x
# 395 passed

uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site
# Strict English and Chinese builds passed

UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py'
UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD
PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD
npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs
git diff --check origin/main...HEAD
# All passed
```

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

Documentation checks also covered bilingual examples and the proactivity
JSON configuration schema. A built-HTML audit verified all 110
historical proactivity section fragments and four title fragments,
including same-language migration destinations, and found zero broken
internal fragment links across 29 HTML pages (672 links). Replaying
pre-fix content made all four page compatibility cases fail as expected.
The new descriptor-directory test failed on all three documents before
their stale paths were corrected. Added coverage exercises tracing
on/off, bare-number versus explicit menu selection with incomplete
classifier configuration, and discovery-menu dispatch through the real
CLI stack's headless sink. Runtime type checks and the full repository
test suite were not run; no runtime code changes. No browser click test,
live LLM, real-VM, or container end-to-end run was performed.

## Risk

Documentation-only, with regression tests. Proactivity navigation
changes, but page URLs and historical heading fragments are preserved.
An old link to content moved between pages lands on a visible migration
entry and requires one click to reach the new section; no JavaScript
redirect is needed. Existing queued-nudge policy and external-agent
isolation limitations are described, not fixed. Roll back by reverting
the documentation and associated test changes; no data migration is
involved.

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

## Related Issues

N/A

---------

Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
2026-09-20 19:20:27 +08:00
..

Raven in Docker

Build and run the current checkout:

cd docker
docker compose up --build

To run the configured image without rebuilding, use docker compose up --no-build. Plain docker compose up may reuse or pull an image rather than rebuild local changes.

Then open http://localhost:18793. The local Compose default signs that browser in automatically so Settings > Models is immediately available.

What comes up

One container, two processes:

process what it does
nginx (:80) serves the built page from /app/ui-web/dist, proxies /rpc, /auth*, /health, /file, /files/, /oauth/callback to the engine
the Raven engine the RPC gateway on 127.0.0.1:18793 inside the container

They share a container because the engine binds loopback only (web.TCPSite(runner, "127.0.0.1", port)), so a proxy in a second container would have nothing to dial. The image builds the page in a Node stage and the Python environment with uv sync --frozen, so both halves come from the same commit.

Signing in

The engine mints a session credential per boot and the page needs a cookie for it. Compose defaults RAVEN_AUTO_LOGIN=1, so nginx gives a browser loading the page that credential automatically. This is intended for a locally published port.

For a remotely exposed deployment, put RAVEN_AUTO_LOGIN=0 in .env.local. The entrypoint prints a one-time link on startup:

raven-docker: sign in once with this one-time link (replace localhost if you are remote):

    http://localhost:18793/auth#<nonce>

The cookie it sets lasts 30 days, and survives a restart -- the engine reloads the same cookie from /data rather than minting a new one.

The page's raven web advice is for a host install. In a container, mint another one-time link with:

docker compose exec raven docker-entrypoint.sh signin

Configuring a provider

The engine starts with nothing configured. It says so on the way up:

! no provider is configured yet -- run `raven onboard` for guided setup
  Starting anyway. Add a provider in Settings > Models on the page.

Add one in the page's Settings > Models and the next turn uses it -- the provider reads its credentials per call, so nothing needs restarting.

To have a deployment come up already configured, declare one in .env.local instead:

RAVEN_PROVIDER=anthropic
RAVEN_API_KEY=sk-ant-...

The entrypoint writes that into config on every boot, so where it is set it is the source of truth.

Local providers can be seeded by address without an API key:

RAVEN_PROVIDER=ollama-chat
RAVEN_API_KEY=
RAVEN_API_BASE=http://host.docker.internal:11434

The container always runs raven gateway, including the page, RPC, IM channels, cron, and the proactivity stack. Its resolving provider re-reads credentials on every call, which is what makes a provider added in Settings work on the next turn.

Settings

.env is committed and holds defaults. The service loads the optional, git-ignored .env.local second for container runtime variables such as provider credentials and RAVEN_AUTO_LOGIN. Put every credential in .env.local.

Compose interpolation is separate: RAVEN_IMAGE, RAVEN_WEB_PORT, RAVEN_EXTRAS, RAVEN_PLUGINS, and RAVEN_OFFICE are resolved before the container starts. Setting them only in the service's .env.local does not override the image, published port, or build arguments. From this directory, use shell variables, for example:

RAVEN_IMAGE=raven:local RAVEN_WEB_PORT=18893 docker compose up --build

Or, after creating .env.local, load it explicitly for interpolation too:

docker compose --env-file .env --env-file .env.local up --build

The later file wins; shell environment values override both files.

Data

Everything durable is under /data on the raven-data volume: config.json, the workspace, sessions, logs and the memory store. Removing the container keeps it; docker compose down -v does not.

Running a CLI command

Any argument that is not run or signin is handed to the raven CLI:

docker compose exec raven docker-entrypoint.sh provider test anthropic
docker compose run --rm raven status

Notes and limits

  • Exposure. The default Compose page automatically grants a Raven browser session to anyone who can reach its port, so the published port binds 127.0.0.1 only. A remote deployment must choose its own bind or proxy and set RAVEN_AUTO_LOGIN=0. nginx also rewrites the Origin header so the engine accepts a browser that reached it through a published port. That drops a defence-in-depth layer; the session cookie is SameSite=Strict, so an unauthenticated socket is still refused. Publish this port only where you would have published the engine's own.
  • HTTPS. Not configured here. Terminate TLS in front of this container; the page picks wss:// from location.protocol on its own.
  • The TUI is not in this image. raven tui needs the Node bundle from ui-tui/, which the image does not build.
  • sandbox. The extra is off by default: inside a container the container is the boundary. Turn it on with RAVEN_EXTRAS if you want boxlite as well.
  • LibreOffice is in the image. The page cannot draw a .docx, .xlsx or .pptx, so the gateway converts those to PDF to show them; without it every office file in a knowledge base, and every deck, answers the viewer with "LibreOffice is not installed" -- a hosted image telling its user to install something on it. It is the largest thing here, roughly 500 MB with the CJK fonts it needs to render anything but Latin text. Build with --build-arg RAVEN_OFFICE=0, or RAVEN_OFFICE=0 in the environment Compose reads, for a deployment that will never preview one.