Operating Omnigraph Locally

This skill captures the operational rules for working with a locally deployed Omnigraph (RustFS-backed or remote S3). Follow them when authoring schema, writing queries, loading data, evolving schema, or automating graph operations.

The Seven Rules

1. Lint before commit — omnigraph query lint --schema schema.pg --query queries/foo.gq validates both sides against each other. No running repo required.
2. Plan before apply — never run schema apply without a successful schema plan first. Apply is destructive; plan is free.
3. Branches are for data; apply is for schema — review data ingests on a feature branch then merge. Schema changes go straight to main.
4. Pick the right write command — change for edits (typechecked, parameterized), load --mode merge for bulk upsert on local repos, ingest for remote, load --mode overwrite only for clean slates.
5. Parameterize everything — never string-interpolate values into .gq bodies or --params. Declare $var: Type and pass via --params.
6. Expose agent operations as aliases — not raw CLI invocations. Aliases decouple the operation name from the query implementation.
7. Verify after every remote write — compare commit list --branch main head before and after. The CLI's exit code is not authoritative on remote graphs; proxies can drop the response while the write commits server-side. See references/remote-ops.md for the verification ritual and how to recover from 504s.

Local Setup

Bootstrap a local RustFS + Omnigraph in one command

Requires Docker. RustFS runs in a container — install Docker and verify before running the bootstrap: