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 lint --schema schema.pg --query queries/foo.gq validates both sides against each other. No running repo required. (omnigraph query lint still works as a deprecated alias.)
2. Plan before apply — never run schema apply without a successful schema plan first. Apply is destructive; plan is free. (Cluster mode has the same rule with different verbs: cluster plan before cluster apply — the plan embeds the engine's real migration steps.)
3. Branches are for data; apply is for schema — review data ingests on a feature branch then merge. Schema changes go straight to main (single-graph: omnigraph schema apply; cluster mode: edit the .pg and run cluster apply — there is no direct schema apply in cluster deployments).
4. Pick the right write command — mutate 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.

Five Ontology Design Criteria (Gruber 1993)

Omnigraph schemas are ontologies. The canonical design criteria from Gruber's Toward Principles for the Design of Ontologies Used for Knowledge Sharing (Int. J. Human-Computer Studies 43:907–928) apply directly when authoring .pg files.