Raven-1/docs/README.md
Dizhan Xue 25c576859a
docs: add the technical report page and link it from the readmes (#812)
## Summary

Adds `docs/technical-report/README.md`, the landing page for the Raven
technical report: title, abstract, BibTeX entry, and a download link for
the PDF. It replaces the zero-byte `.gitkeep` that created the folder,
and `docs/README.md` gains the index entry that the placeholder change
deferred until real content landed.

Both root READMEs link the PDF itself rather than that page: a Technical
Report link leads the navigation line under the badges, and a closing
Citation section, after License, carries the same BibTeX entry and links
the same file. The English and Chinese READMEs change in the same
places, and the three BibTeX blocks are byte-identical.

The PDF itself (4,035,271 bytes, 82 pages) is not committed. AGENTS.md
section 7 keeps report assets and files over 1 MiB out of git, and
`scripts/check_large_files.py` rejects this file on both counts. It is
attached to the `tech-report-v1` release instead, published with
`--latest=false`: `/releases/latest` is what `install.sh`, `install.ps1`
and `raven/updates/upgrade.py` resolve, and all three accept only a
`vX.Y.Z` tag there. The report tag points at the v0.2.3 commit. A later
revision of the report gets its own release rather than replacing this
asset.

## Type

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

## Verification

Every range below starts at the branch base, the #810 squash on `main`.

- `scripts/check_large_files.py <base>..HEAD`: exit 0.
- `scripts/check_source_language.py <base>..HEAD`: exit 0.
- `scripts/check_commit_messages.py <base>..HEAD`: exit 0.
- `commitlint --from <base> --to HEAD --config commitlint.config.cjs`:
exit 0.
- `pre-commit run --from-ref <base> --to-ref HEAD`: exit 0. The hooks
that match these files passed and modified nothing.
- `pytest -q tests/test_living_docs.py tests/test_docs_site.py
tests/test_large_file_check.py tests/test_docker_runtime.py`: 41 passed.
`test_docker_runtime.py` is the one test that reads both root READMEs.
- All three pages rendered through the GitHub markdown API. The landing
page shows the abstract's en dash, both emphasized terms, the two links
and the BibTeX block; each root README shows the Technical Report link
first in its navigation line, both of its report links resolve to the
PDF download URL, and it ends with the Citation section and its BibTeX
block.
- The release asset's digest equals the local file's SHA-256
(`14832f50...`). After publishing,
`https://github.com/EverMind-AI/Raven/releases/latest` still redirects
to `v0.2.3`, and the release page and the PDF download URL both return
200 to an anonymous request.

`make lint` was not run: `PYTHON_LINT_TARGETS` and the TypeScript lint
trees do not include `docs/` or the root READMEs.

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

## Risk

Docs only: nothing reads these files at runtime. The release is the part
with reach: it is public, publishing it notified release watchers, and
it must never become Latest. If it has to be withdrawn, `gh release
delete tech-report-v1 -R EverMind-AI/Raven --cleanup-tag` removes it and
its tag, and the landing page's links then 404 until the page is
reverted. Rolling back this PR is a revert of the squash commit.

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

## Related Issues

#804 created the folder this page fills.

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-09-27 20:07:07 +08:00

2.2 KiB

Raven Documentation

This directory holds design notes, dated records, and developer references that are too detailed for the main README.

For first-time users, start at the root README.md. Domain terms live in CONTEXT.md, routed from CONTEXT-MAP.md. Several files below are dated records kept for their history rather than descriptions of the current tree; each such file carries a banner saying so.

Index

  • showcase.md / showcase.zh-CN.md - more showcases, linked from each root README: real runs, each shown as its task graph and what the run produced.
  • technical-report/ - the Raven technical report: abstract, citation, and a link to the PDF, which lives on a GitHub Release rather than in git.
  • documentation-references.md - public reference sources and implementation evidence behind the protocol, orchestration, permissions, and extension guides.
  • dev.md - local development notes.
  • browser-and-desktop.md - the model's browser_* tools over the shared Chromium, and desktop control through a desktop MCP server; enabling, permissions, what was verified.
  • TRACING_STANDARD_API.md - the tracing span contract between raven and raven-tracing.
  • research-report-quality.md - how a deep-research report is graded against a competitor's, and what scripts/research_report_audit.py settles mechanically.
  • sandbox/ - BoxLite sandbox usage and debugging notes.
  • specs/ - dated design records (YYYY-MM-DD-*.md) plus the self-evolution SOP and playbook specs; each describes the tree as of its date.
  • plans/ - historical implementation plans; an archive, deliberately not held to today's layout.
  • examples/ - benchmark and runtime configuration examples.
  • Proactivity-Plan.md / Proactivity-Implementation.md - proactive-behavior design intent and as-built notes.
  • Proactivity-Cost-Analysis.md - dated cost snapshot (2026-04).
  • memory-plugin-architecture.md - design record for the memory-plugin architecture; the bundled-in-tree layout it proposes was superseded by plugins-dist/.
  • everos-memory-e2e-test-plan.md - dated end-to-end memory validation plan.
  • skill-hub-integration-design.md - design record; shipped as raven/skill_hub/.