* docs: state cluster apply is storage-direct, not server-routed
`cluster apply` reaches the object store directly — the `__cluster/` ledger
and each graph's Lance datasets — never through a running omnigraph-server,
so the host that runs it needs storage credentials. The rationale (declarative
control plane, not a runtime mutation API) was documented in cluster-axioms.md
§3/§4, and the out-of-band/direct-storage fact was stated for the maintenance
verbs and init/load, but never spelled out for apply itself.
- docs/user/clusters/index.md: add a day-2 note making apply's storage-direct
execution and credential requirement explicit, linking the why to axioms 3/4.
- skills/omnigraph/SKILL.md: extend the "init/load write storage directly
(bypassing the server)" line to include cluster apply, with the same reasoning.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: disambiguate the §5 cross-reference in cluster apply note
The trailing (§5) sat right after the cluster-axioms.md §3/§4 citation, so a
reader could read §5 as referring to cluster-axioms.md (whose §5 covers locked
state) rather than this guide's §5. Make it an explicit same-page forward
reference. Addresses Greptile P2 on #306.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: don't claim the server is read-only against storage
The "server only reads from it" wording was wrong: the data plane serves HTTP
writes (mutate/load/branch) that go through the server to the graph datasets,
so omnigraph-server is not read-only against object storage. The hazard is an
operator granting the server read-only S3 creds and breaking runtime writes.
Scope the read-only claim to cluster (control-plane) state at boot, and state
that data-plane writes still need read-write storage access. Addresses Greptile
P-level finding on #306.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Ragnor Comerford <ragnor.comerford@gmail.com>
* docs: optimize README for dev onboarding; fix 0.7.0 staleness
The README's setup half drifted from the shipped 0.7.0 CLI and led with the
heaviest path (Docker + RustFS). This reworks it for fast, correct onboarding:
README.md
- New zero-dependency "Your first graph in 60 seconds" hero: a fully
copy-pasteable local file-backed loop (schema → init → load → query → branch).
- Add a correct "Serve it" section (cluster apply + omnigraph-server --cluster);
the server is cluster-only on main, so the old positional-URI boot is gone.
- Demote the RustFS bootstrap to "rehearse the S3 path locally"; reframe the
storage bullet as "filesystem or any S3-compatible store (AWS S3, R2, MinIO,
RustFS)" — RustFS is a provider, not a storage class.
- Fix crate/MCP descriptions (query/mutate/load, not read/change/ingest).
docs/user/quickstart.md
- Fix the query example: `read --name <q> … <uri>` is removed — the query name
is positional and the graph is addressed with `--store` (`omnigraph query
find_people --query queries.gq --store graph.omni`).
scripts/local-rustfs-bootstrap.sh
- Convert to cluster mode: write a cluster.yaml (storage: s3://…), then
validate → import → apply, load the fixture into the derived root with the
now-required --mode, and serve with `omnigraph-server --cluster`. The old
flow (`load` without --mode, `omnigraph-server <URI>` positional boot) no
longer works on a cluster-only server.
* docs: move agent skill into the repo, add agent-setup snippet, drop rustfs script
skills/omnigraph
- The operational skill (formerly `omnigraph-best-practices` in the cookbooks
repo) now lives with the engine it documents, co-versioned. Renamed to
`omnigraph`; repository metadata repointed here.
- Broadened the description to trigger on intent — storing/retrieving/querying
knowledge, agent memory, building a knowledge graph, operating Omnigraph — as
well as on CLI/artifact sightings (stays ≤1024 chars).
- Install: `npx skills add ModernRelay/omnigraph@omnigraph`.
README
- New "Set it up with an AI agent" paste snippet: installs the skill, reads the
docs (URL), browses the cookbooks, and asks the user about a use case before
standing up a first graph.
- "Agent skill & starter graphs" section points at skills/omnigraph + cookbooks.
Drop scripts/local-rustfs-bootstrap.sh
- Not CI-tested (so it rotted: it broke on the cluster-only migration — positional
server boot, load without --mode), demoed the now-optional S3 path, and was the
most fragile artifact in the repo. Replaced with a "Testing against S3 locally"
guide in deployment.md (docker run RustFS/MinIO + AWS_* env + cluster-on-S3).
README/AGENTS references updated.
