Skip to content

docs: refocus README on introduction and getting started - #800

Draft
dremnik wants to merge 2 commits into
ModernRelay:mainfrom
dremnik:docs/simplify-readme
Draft

dremnik wants to merge 2 commits into
ModernRelay:mainfrom
dremnik:docs/simplify-readme

Conversation

@dremnik

@dremnik dremnik commented Sep 28, 2026 •

Copy link
Copy Markdown

1. Purpose

This PR intends to simplify + refocus the README on introducing Omnigraph and helping new users get started, moving detailed instructions to the docs.

I propose that the README should serve 3 main goals:

  1. Establish relevance. Explain what Omnigraph is and what makes it uniquely useful.
  2. Help the reader understand how it fits in their world. Give readers a high-level picture of how Omnigraph works and how they would use it, with enough context to take the next step.
  3. Give readers that next step. Make it easy to install, try the quickstart, or find the relevant documentation (primarily through their agents).

The README provides the explanation for evaluation, a clear path to trying it, and navigation for returning readers; the opening need not explain the whole product or setup instructions.

Below are a few proposed example reader scenarios:

Reader arrives at the README
│
├── a) Evaluating Omnigraph
│   ├── First encounter → What is it? Why should I care?
│   ├── Comparing alternatives → Why use this instead of Postgres?
│   └── Considering a use case → How does it work? Where does it fit in my world?
│
├── b) Trying Omnigraph
│   ├── Wants a working example → Quickstart / cookbooks
│   └── Ready to set it up → Install / agent setup / deployment docs
│
└── c) Returning with a specific task
    ├── Using or operating it → User guides / reference docs
    ├── Building or contributing → Contributor / developer guides
    └── Seeking help or reporting a problem → Community / issues

Detailed usage belongs in docs/user/; build instructions and architecture belong in the contributor and developer guides. Linking to these avoids duplicating instructions that can drift.

2. Changes

ID Change Rationale
CH-01 Number the sections and lead with “Popular use cases,” then “How it works” (Key capabilities and Running Omnigraph), then Getting started (including agent setup). Hook attention through social proof (“popular” suggests others are using it), timely and recognizable examples, and a breadth of applications that signals adaptability to different needs. Explain the model and capabilities before installation, with clear sections for navigation.
CH-02 Replace the deployment walkthrough with a typed graph introduction, typed schema example, branching overview, and cluster configuration. Explain the data model before deployment structure. The Person/Organization snippet makes it concrete; familiar code syntax introduces a new way of modeling data and invites further exploration. Leave detailed setup to the linked guides.
CH-03 Replace the local quick test with a link to docs/user/quickstart.md. The quickstart covers the same example, adds branching and merging, and avoids maintaining a duplicate.
CH-04 Remove Build And Test and Workspace Crates. CONTRIBUTING.md and docs/dev/architecture.md already cover them.
CH-05 Remove Clients & SDKs. Keep the README focused on understanding and trying Omnigraph.
CH-06 Remove the duplicate Slack link. One community link is enough.
CH-07 Revise the capability table to distinguish multimodal data, branching, scale, retrieval, and storage. Give multimodal data its own emphasis and make data volume and speed explicit; performance claims remain an open question below.
CH-08 Link llms.txt in the top navigation and both llms.txt and llms-full.txt under Docs. Make documentation immediately discoverable by readers and the agents they point at the repo.

3. Open questions

  • TODO: Refine the two-sentence description, starting with a stronger opening sentence that explains what Omnigraph is and why someone would use it.
  • What data volumes, concurrency, and retrieval performance should we highlight here?
  • Could we add a short explainer / intro video directly beneath the Slack invitation, before Popular use cases, with a polished graph visualization as its thumbnail? Placeholder for a future video; no asset selected yet.

4. Contribution status

Draft shared for discussion under GOVERNANCE.md’s “Draft vs ready” policy; no backing issue is required for this stage. The opening pitch and performance claims remain unsettled. Before requesting formal review, confirm whether this qualifies for the documentation fast-lane or needs an accepted issue.

Blast radius: README.md only; no runtime, API, schema, or storage behavior changes.

5. Checklist

  • Change is focused on README organization and wording.
  • Behavior tests: N/A; documentation-only change.
  • Public documentation updated in the README.
  • Reviewed against architectural invariants; no implementation or invariant changes.

6. Local verification

  • git diff --check -- README.md — passed.
  • bash scripts/check-agents-md.sh — passed.
  • python3 scripts/check-docs.py — passed (153 Markdown files).
  • typos — not run; executable unavailable locally.
  • Runtime tests — not run; no code changes.

@ragnorc

ragnorc commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

Really like this!
I've also been thinking to change the tagline, as "context assembly" and "coordination layer" is maybe a bit too abstract.
Something like "Object-storage native graph database with branching and typed ontology.". "Give your agents a shared knowledge graph. On object storage so volume can scale definitely and cheaply. With branching so agents propose changes rather than writing directly. With typed ontology so agents have a shared enforceable model of the domain".

@ragnorc

ragnorc commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Also should add an image? Often explains more than a 1000 words cc @pronskiy

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants