From 4e431d28b8a463be50770fc1ccfdc87c8439c2ef Mon Sep 17 00:00:00 2001 From: Andrew Altshuler Date: Sat, 30 May 2026 00:53:42 +0100 Subject: [PATCH] docs: rewrite README opening + add AGENTS.md dev commands (#122) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(agents): add build/test/lint dev-command section AGENTS.md (CLAUDE.md) covered architecture and invariants but had no developer command surface — only runtime `omnigraph` CLI usage. Add a concise "Build, test, lint" section with the non-obvious gotchas: - crate dir `crates/omnigraph` is package `omnigraph-engine` (the `-p` name) - canonical CI gate is `cargo test --workspace --locked` - how to run one file / one fn - feature-gated suites (`failpoints`, server `aws`) - S3 tests skip without `OMNIGRAPH_S3_TEST_BUCKET` - the two non-test CI checks (check-agents-md, OpenAPI drift) Co-Authored-By: Claude Opus 4.8 (1M context) * docs(readme): rewrite opening, dedupe, fix stale references - New manifesto-style opening (tagline, X-as-code, features, core use cases, coordination-layer line); drop the old prose intro, Use Cases, and Capabilities sections. - Remove Capabilities, which restated the new opening line-for-line. - Harmonize heading case: "## Core Use Cases". - Dedupe the verbatim Slack invite (kept the Community section) and the double-linked cli.md (kept the contextual pointer). - Fix stale references that no longer match the code: - drop "transactional runs" / "and runs" — no run concept remains; writes are atomic per-query, multi-query workflows use branches. - update the CLI crate command list to canonical query/mutate plus commit/lint/optimize/cleanup. Co-Authored-By: Claude Opus 4.8 (1M context) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- AGENTS.md | 26 ++++++++++++++++++++++++++ README.md | 45 ++++++++++++++++++++------------------------- 2 files changed, 46 insertions(+), 25 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 27d1b7b..3fc78f7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,6 +164,32 @@ If a proposal fits one of these, the burden is on the proposer to justify why th --- +## Build, test, lint + +Rust stable workspace (edition 2024). `protoc` is a build dependency (`brew install protobuf` / `apt-get install protobuf-compiler libprotobuf-dev`). **Crate dir ≠ package name** for the engine: the directory is `crates/omnigraph` but its Cargo package is `omnigraph-engine` (use that in `-p`). The CLI binary built from `omnigraph-cli` is named `omnigraph`. + +```bash +cargo build --workspace --locked # build everything +cargo test --workspace --locked # the canonical CI gate (matches CI exactly) +cargo run -p omnigraph-cli -- # run the `omnigraph` CLI from source +cargo run -p omnigraph-server -- --bind 0.0.0.0:8080 # run the server from source + +# Run one crate / one test file / one test fn +cargo test -p omnigraph-engine --test traversal # one integration-test file (see docs/dev/testing.md) +cargo test -p omnigraph-engine --test runs concurrent # one test fn by name substring +cargo test -p omnigraph-engine some_inline_test -- --nocapture # show stdout + +# Feature-gated suites (each is its own job in CI, not part of the default run) +cargo test -p omnigraph-engine --features failpoints --test failpoints # fault injection +cargo build -p omnigraph-server --features aws # AWS Secrets Manager bearer-token source +``` + +S3-backed tests (`s3_storage`, and the S3 paths in server/CLI system tests) **skip** unless `OMNIGRAPH_S3_TEST_BUCKET` + `AWS_*` (incl. `AWS_ENDPOINT_URL_S3` for non-AWS) are set; CI runs them against containerized RustFS. `scripts/local-rustfs-bootstrap.sh` stands up a local S3 environment. + +CI does **not** run `clippy` or `rustfmt` as gates — but `cargo test --workspace --locked` is the exact gate, so run it before pushing. Two non-test CI checks: `scripts/check-agents-md.sh` (doc cross-link integrity — run it after moving/renaming docs) and OpenAPI drift (`crates/omnigraph-server/tests/openapi.rs` regenerates `openapi.json`; set `OMNIGRAPH_UPDATE_OPENAPI=1` to update the checked-in copy when a server/API change is intentional). + +--- + ## Quick-reference flows ```bash diff --git a/README.md b/README.md index ae3234b..5291580 100644 --- a/README.md +++ b/README.md @@ -5,33 +5,29 @@ [![Crates.io](https://img.shields.io/crates/v/omnigraph-cli.svg)](https://crates.io/crates/omnigraph-cli) [![CI](https://github.com/ModernRelay/omnigraph/actions/workflows/ci.yml/badge.svg)](https://github.com/ModernRelay/omnigraph/actions/workflows/ci.yml) -**Object-storage native knowledge graph with git-style workflows. Designed for agents and humans to collaborate on shared structured knowledge.** +**Lakehouse native graph engine built for context assembly** -Turns fragmented context into a live graph, lets humans and agents coordinate through that graph, and uses branches so agent-generated changes can be reviewed and merged safely. +Schema AS CODE +Context AS CODE +Security AS CODE +Dashboards AS CODE -Built on Rust, Arrow, DataFusion and Lance. +Git-style snapshots & branching +Object storage native (S3, RustFS) +VPC, On-prem, hybrid deployment +Lance format as storage layer -Join the [Omnigraph Slack community](https://join.slack.com/t/omnigraphworkspace/shared_invite/zt-3wfpglyxj-lHvJGhuySPfqLtN35uJZNw) +## Core Use Cases -## Use Cases - -- Company brain / [Second brain](https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/second-brain) +- Company brain - Context graph -- Knowledge base for multi-agent research -- Incident response graph -- Compliance & audit graph +- Agentic memory +- Code & dev graph +- R&D data layer +- ML workflows +- Karpathy's LLM wiki - -## Capabilities - -- Typed schema, typed queries, and typed mutations -- Native blob-as-data support (docs, images, videos, etc) -- Schema-as-code, query validation and linting -- Git-style graph workflows: branches, commits, merges, and transactional runs -- Local, on-prem & cloud S3-native storage with snapshot-pinned reads -- Graph traversal + text, fuzzy, BM25, vector, and RRF search in one runtime -- Policy-as-code for server-side access control -- Single CLI for multiple deployments +Omnigraph acts as operational state & coordination layer for agents ## Quick Install @@ -86,12 +82,11 @@ omnigraph branch create --from main feature-x ./graph.omni omnigraph branch merge feature-x --into main ./graph.omni ``` -See [docs/user/cli.md](docs/user/cli.md) for schema apply, snapshots, ingest, runs, and policy commands. +See [docs/user/cli.md](docs/user/cli.md) for schema apply, snapshots, ingest, commits, and policy commands. ## Docs - [Install guide](docs/user/install.md) -- [CLI guide](docs/user/cli.md) - [Deployment guide](docs/user/deployment.md) ## Build And Test @@ -113,8 +108,8 @@ Notes: - `crates/omnigraph-compiler`: shared schema/query parser, typechecker, catalog, and IR lowering - `crates/omnigraph`: storage/runtime, branching, merge, change detection, and query execution -- `crates/omnigraph-cli`: CLI for init/load/ingest/read/change/branch/snapshot/export/policy operations -- `crates/omnigraph-server`: Axum HTTP server for remote reads, changes, ingest, export, branches, commits, and runs +- `crates/omnigraph-cli`: CLI for graph lifecycle (init/load/ingest), query/mutate, branch/commit/merge, schema/lint, snapshot/export, policy, and maintenance (optimize/cleanup) +- `crates/omnigraph-server`: Axum HTTP server for remote reads, changes, ingest, export, branches, and commits ## Contributing