docs: rewrite README — content-first, drop GIFs, link to website#23
Merged
Conversation
The previous README leaned on three large GIFs (`hero.gif`,
`oracle_26ai/demo.gif`, `build-an-agent.gif`) and stale exact-count
test badges (``2,987 unit / 330+ integration``). The website at
oracle-samples.github.io/locus is now the authoritative content
source for screenshots / diagrams / GIFs; this README's job is the
30-second orientation that points the reader there.
Changes
-------
- Drop all three demo GIFs.
- Keep the two informative SVG diagrams (``agent-loop.svg``,
``architecture.svg``).
- Trim badges to status-style only — Python version, license, mypy
strict, ruff clean, OCI day-0. No more brittle test counts.
- Replace the "Architecture / One run end-to-end / Quick start /
Capabilities" sequence with a tighter flow:
1. One-line pitch + bash install.
2. Hello-agent code block (kept verbatim — it's the load-bearing
teaser).
3. ``What you get`` table — every row links to the matching
concept page on the website.
4. ``The agent loop`` (one SVG + 4-bullet narration + link).
5. ``Architecture`` (one SVG, 1-line caption).
6. ``Multi-agent`` table (six in-process patterns + A2A).
7. ``Quick start`` (12-line scheduling agent).
8. ``Tutorials`` table grouped by track + 3 demo links.
9. ``Repo layout`` text tree.
10. ``Contributing`` with the new ``hatch run check`` gate.
11. ``Citing GSAR`` BibTeX block.
12. ``License`` one-liner.
- README dropped from 502 → 292 lines.
- Tutorial counter says ``39 progressive tutorials`` (was 38; matches
current state after !100 / PR #19).
- ``Six coordination patterns plus A2A`` framing throughout (matches
the alignment landed in PR #7).
Drive-by
--------
- New ``Citing GSAR`` section with BibTeX block pointing at
``arXiv:2604.23366`` so production users / academics have a clean
citation handle.
- Documentation row links go to website concept pages, not local
files — readers landing on GitHub now find their way to the
curated website content rather than ad-hoc markdown.
Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The previous README leaned on three large demo GIFs (`hero.gif`, `oracle_26ai/demo.gif`, `build-an-agent.gif`) and stale exact-count test badges (`2,987 unit / 330+ integration`). With the docs site at https://oracle-samples.github.io/locus/ now the authoritative content source for diagrams, screenshots, and longer-form content, this README's job is the 30-second orientation that points readers there.
Changes
Drive-bys
Test plan