Skip to content

docs: rewrite README — content-first, drop GIFs, link to website#23

Merged
fede-kamel merged 1 commit into
mainfrom
docs/readme-content-focused
May 1, 2026
Merged

docs: rewrite README — content-first, drop GIFs, link to website#23
fede-kamel merged 1 commit into
mainfrom
docs/readme-content-focused

Conversation

@fede-kamel
Copy link
Copy Markdown
Contributor

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

  • Drop all 3 demo GIFs (the "weird videos").
  • 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.
  • Tighter narrative flow (replaces the previous Architecture / One run end-to-end / Quick start / Capabilities sequence):
    1. One-line pitch + bash install.
    2. Hello-agent code block (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 to the architecture page).
    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 502 → 292 lines (-42%).
  • Tutorial counter says `39 progressive tutorials` (was 38; matches current state after PR feat: GSAR Agent integration — Agent(gsar=GSARConfig(...)) #19).
  • `Six coordination patterns plus A2A` framing throughout (matches PR docs: align multi-agent count — six in-process patterns plus A2A #7 alignment).

Drive-bys

  • New `Citing GSAR` section with BibTeX block pointing at `arXiv:2604.23366` so production users / academics have a clean citation handle.
  • `What you get` row links go to website concept pages, not local markdown — readers landing on GitHub now find their way into curated website content.

Test plan

  • CI passes (`CI Success` aggregator: format-check + lint + mypy across Python 3.11/3.14, tests across 3.11/3.12/3.13/3.14, pre-commit, DCO).
  • All links in the README resolve (the website concept pages exist; tutorial paths exist in `examples/`).

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>
@oracle-contributor-agreement oracle-contributor-agreement Bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label May 1, 2026
@fede-kamel fede-kamel merged commit 65ff9b2 into main May 1, 2026
10 checks passed
@fede-kamel fede-kamel deleted the docs/readme-content-focused branch May 13, 2026 04:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant