docs: onboarding-first README + in-repo agent skill + drop RustFS script (#257)

* 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.
This commit is contained in:
Ragnor Comerford 2026-06-16 11:48:13 +02:00 committed by GitHub
parent 05cb73eda6
commit ee4986e9a1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 2297 additions and 481 deletions

View file

@ -129,49 +129,46 @@ shape above) — the simplest AWS architecture.
unvalidated** — boot is lock-free read-only so it should compose, but it
is not yet exercised by tests.
## One-Command Local RustFS Bootstrap
## Testing against S3 locally
The easiest local S3-backed deployment path is:
To exercise the S3 storage path without a cloud account, run any S3-compatible
store in Docker and point the standard `AWS_*` environment at it. RustFS is
shown; MinIO works the same way.
```bash
curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/local-rustfs-bootstrap.sh | bash
docker run -d --name omnigraph-s3 -p 9000:9000 \
-e RUSTFS_ACCESS_KEY=omnigraph -e RUSTFS_SECRET_KEY=omnigraph \
-e RUSTFS_ALLOW_INSECURE_DEFAULT_CREDENTIALS=true \
rustfs/rustfs:latest /data
export AWS_ACCESS_KEY_ID=omnigraph AWS_SECRET_ACCESS_KEY=omnigraph \
AWS_REGION=us-east-1 AWS_ENDPOINT_URL_S3=http://127.0.0.1:9000 \
AWS_ALLOW_HTTP=true AWS_S3_FORCE_PATH_STYLE=true
# create the bucket once (any S3 client works)
aws --endpoint-url "$AWS_ENDPOINT_URL_S3" s3 mb s3://omnigraph-local
```
The bootstrap:
Now an `s3://…` URI works anywhere a graph or cluster root is expected. Root a
cluster on the bucket and serve it config-free:
- starts a local RustFS-backed object store
- creates a bucket and S3-backed Omnigraph graph
- loads the checked-in context fixture
- starts `omnigraph-server` on `127.0.0.1:8080`
```bash
# cluster.yaml
# version: 1
# storage: s3://omnigraph-local/clusters/demo
# graphs: { demo: { schema: schema.pg } }
Supported behavior:
omnigraph cluster validate --config .
omnigraph cluster import --config .
omnigraph cluster apply --config . --as you
omnigraph load --data seed.jsonl --mode merge \
s3://omnigraph-local/clusters/demo/graphs/demo.omni
omnigraph-server --cluster s3://omnigraph-local/clusters/demo \
--bind 127.0.0.1:8080 --unauthenticated
```
- downloads the rolling `edge` binary when one exists for the current platform
- otherwise clones `ModernRelay/omnigraph` and builds from source
- reuses an existing RustFS container if it is already running
Useful overrides:
- `WORKDIR=/path/to/state`
- `BUCKET=omnigraph-local`
- `PREFIX=graphs/context`
- `RESET_REPO=1` to delete an existing partially initialized graph prefix before recreating it
- `BIND=127.0.0.1:8080`
- `RUSTFS_CONTAINER_NAME=omnigraph-rustfs-demo`
The bootstrap expects:
- Docker
- `curl`
- either a matching release asset or a local Rust toolchain plus `git`
If `aws` is not installed, the script attempts a user-local AWS CLI install via
`python3 -m pip`. Docker Desktop or another Docker daemon must already be
running.
If a previous bootstrap left objects behind under the selected `PREFIX` but did
not finish initializing the graph, rerun with `RESET_REPO=1` or choose a new
`PREFIX`.
The same `AWS_*` contract applies to a production object store — swap the
endpoint and credentials. CI exercises this path against containerized RustFS.
## Container Deployment

View file

@ -53,10 +53,13 @@ query find_people($title: String) {
Run it:
```bash
omnigraph read --query queries.gq --name find_people \
--params '{"title":"Engineer"}' --format table graph.omni
omnigraph query find_people --query queries.gq \
--params '{"title":"Engineer"}' --format table --store graph.omni
```
The query name is positional; `--query` points at the `.gq` source and
`--store` addresses the graph's storage directly.
The [query language](queries/index.md) covers `match`/`return`/`order`, and
[search](search/index.md) covers vector and full-text search.