docs(readme): align with cluster-first paradigm + RFC-011 CLI ergonomics (#262)

* docs(readme): align with the cluster-first paradigm + RFC-011 CLI ergonomics

The README's command examples and crate list predated 0.7.0. Update them:

- Common Commands: capability/addressing model — positional/`--store` for direct
  storage, `--server` for served graphs (no positional `http(s)://`), `query`/
  `mutate` invoke a stored query by name (positional is the query name), `load`
  requires `--mode`. Drop the false "same URI works for local/s3/http" claim and
  the deprecated `read`/`change` + `--name` forms; mention `~/.omnigraph/config.yaml`.
- New "Serving (cluster-first)" section: a deployment is a cluster.yaml converged
  with `cluster apply` and served by `omnigraph-server --cluster <dir|s3://…>`
  (no single-graph mode; config-free boot from a bucket).
- Fix the stale docs link (`docs/user/cli.md` → `cli/index.md` + the CLI reference)
  after the docs were restructured into topic sections.
- Workspace Crates: list all seven (add omnigraph-policy, omnigraph-api-types,
  omnigraph-cluster) with cluster-first framing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(agents): fix the stale `read --name` quick-reference example

AGENTS.md (always-loaded; symlinked to CLAUDE.md) still showed the deprecated
`omnigraph read --query … --name … <s3-uri>` form. Update it to the RFC-011
shape: `omnigraph query --query … <name> … --store <uri>` (read→query, --name→
positional query name, positional URI→--store). Addresses the bot-review finding
on #262.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Andrew Altshuler 2026-06-16 11:18:16 +03:00 committed by GitHub
parent e539aa1693
commit a83da2ccfd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 51 additions and 15 deletions

View file

@ -210,9 +210,9 @@ omnigraph load --data ./seed.jsonl --mode overwrite s3://my-bucket/graph.omni
# Load a review batch onto its own branch (--from forks it if missing)
omnigraph load --branch review/2026-04-25 --from main --mode merge --data ./batch.jsonl s3://my-bucket/graph.omni
# Run a hybrid (vector + BM25) query
omnigraph read --query ./queries.gq --name find_similar \
--params '{"q":"trends in AI safety"}' --format table s3://my-bucket/graph.omni
# Run a hybrid (vector + BM25) query — ad-hoc .gq against a store (positional = query name)
omnigraph query --query ./queries.gq find_similar \
--params '{"q":"trends in AI safety"}' --format table --store s3://my-bucket/graph.omni
# Plan + apply schema migration
omnigraph schema plan --schema ./next.pg s3://my-bucket/graph.omni