Initial public Omnigraph repository

docs/cli.md

@@ -0,0 +1,89 @@
+# CLI Guide
+
+## Core Repo Flow
+
+```bash
+omnigraph init --schema ./schema.pg ./repo.omni
+omnigraph load --data ./data.jsonl --mode overwrite ./repo.omni
+omnigraph snapshot ./repo.omni --branch main --json
+omnigraph read ./repo.omni --query ./queries.gq --name get_person --params '{"name":"Alice"}'
+omnigraph change ./repo.omni --query ./queries.gq --name insert_person --params '{"name":"Mina","age":28}'
+```
+
+## Branching And Reviewable Data Flows
+
+```bash
+omnigraph branch create --uri ./repo.omni --from main feature-x
+omnigraph branch list --uri ./repo.omni
+omnigraph branch merge --uri ./repo.omni feature-x --into main
+
+omnigraph ingest --data ./batch.jsonl --branch review/import-2026-04-09 ./repo.omni
+omnigraph export ./repo.omni --branch main --type Person > people.jsonl
+omnigraph commit list ./repo.omni --branch main --json
+omnigraph commit show --uri ./repo.omni <commit-id> --json
+```
+
+## Remote Server Mode
+
+Serve a repo:
+
+```bash
+omnigraph-server ./repo.omni --bind 127.0.0.1:8080
+```
+
+Read through the HTTP API:
+
+```bash
+omnigraph read \
+  --target http://127.0.0.1:8080 \
+  --query ./queries.gq \
+  --name get_person \
+  --params '{"name":"Alice"}'
+```
+
+If the server requires auth, set `OMNIGRAPH_SERVER_BEARER_TOKEN` on the server
+and configure the matching `bearer_token_env` in `omnigraph.yaml`.
+
+## Runs, Policy, And Diagnostics
+
+```bash
+omnigraph schema plan --schema ./next.pg ./repo.omni --json
+omnigraph policy validate --config ./omnigraph.yaml
+omnigraph policy test --config ./omnigraph.yaml
+omnigraph policy explain --config ./omnigraph.yaml --actor act-alice --action read --branch main
+
+omnigraph run list ./repo.omni --json
+omnigraph run show --uri ./repo.omni <run-id> --json
+omnigraph run publish --uri ./repo.omni <run-id> --json
+omnigraph run abort --uri ./repo.omni <run-id> --json
+```
+
+## Config
+
+`omnigraph.yaml` lets the CLI and server share named targets, defaults, and
+query roots:
+
+```yaml
+targets:
+  local:
+    uri: ./demo.omni
+  dev:
+    uri: http://127.0.0.1:8080
+    bearer_token_env: OMNIGRAPH_BEARER_TOKEN
+
+cli:
+  target: local
+  branch: main
+
+query:
+  roots:
+    - queries
+    - .
+```
+
+The config file can also define:
+
+- server bind defaults
+- auth env files
+- query aliases for common read and change commands
+- `policy.file` for Cedar authorization rules

docs/deployment.md

@@ -0,0 +1,125 @@
+# Deployment
+
+This doc describes the public runtime contract for self-hosting Omnigraph. It
+does not include environment-specific secrets, private infrastructure, or
+internal deploy automation.
+
+## Runtime Modes
+
+Omnigraph supports two broad deployment shapes:
+
+- local directory repos
+- `s3://` repos on AWS S3 or S3-compatible object stores
+
+The server binary and container image expose the same HTTP surface.
+
+## Binary Deployment
+
+Build or install:
+
+- `omnigraph`
+- `omnigraph-server`
+
+Run against a local repo:
+
+```bash
+omnigraph-server ./repo.omni --bind 0.0.0.0:8080
+```
+
+Run against an object-store-backed repo:
+
+```bash
+OMNIGRAPH_SERVER_BEARER_TOKEN="change-me" \
+AWS_REGION="us-east-1" \
+omnigraph-server s3://my-bucket/repos/example/releases/2026-04-10-v0.1.0 \
+  --bind 0.0.0.0:8080
+```
+
+## One-Command Local RustFS Bootstrap
+
+The easiest local S3-backed deployment path is:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/local-rustfs-bootstrap.sh | bash
+```
+
+The bootstrap:
+
+- starts a local RustFS-backed object store
+- creates a bucket and S3-backed Omnigraph repo
+- loads the checked-in context fixture
+- starts `omnigraph-server` on `127.0.0.1:8080`
+
+Supported behavior:
+
+- downloads a tagged release binary when one exists for the current platform
+- otherwise clones `ModernRelay/omnigraph-public` and builds from source
+- reuses an existing RustFS container if it is already running
+
+Useful overrides:
+
+- `WORKDIR=/path/to/state`
+- `BUCKET=omnigraph-local`
+- `PREFIX=repos/context`
+- `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.
+
+## Container Deployment
+
+Build the image:
+
+```bash
+docker build -t omnigraph-server:local .
+```
+
+Run against a local repo:
+
+```bash
+docker run --rm -p 8080:8080 \
+  -v "$PWD/repo.omni:/data/repo.omni" \
+  omnigraph-server:local \
+  /data/repo.omni --bind 0.0.0.0:8080
+```
+
+Run against an S3-backed repo:
+
+```bash
+docker run --rm -p 8080:8080 \
+  -e OMNIGRAPH_SERVER_BEARER_TOKEN="change-me" \
+  -e AWS_REGION="us-east-1" \
+  omnigraph-server:local \
+  s3://my-bucket/repos/example/releases/2026-04-10-v0.1.0 \
+  --bind 0.0.0.0:8080
+```
+
+## Auth
+
+The server can run unauthenticated for local development, but any shared or
+internet-facing deployment should set:
+
+- `OMNIGRAPH_SERVER_BEARER_TOKEN`
+
+The health endpoint `/healthz` remains suitable for load balancer health checks.
+
+## S3-Compatible Storage
+
+For S3-compatible backends such as RustFS or MinIO, set the usual AWS SDK
+environment variables:
+
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_REGION`
+- optional `AWS_ENDPOINT_URL`
+- optional `AWS_ENDPOINT_URL_S3`
+- optional `AWS_ALLOW_HTTP=true`
+- optional `AWS_S3_FORCE_PATH_STYLE=true`

docs/install.md

@@ -0,0 +1,66 @@
+# Install
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/install.sh | bash
+```
+
+By default the installer places:
+
+- `omnigraph`
+- `omnigraph-server`
+
+in `~/.local/bin`.
+
+If a matching release asset exists for your platform, the installer downloads
+and unpacks it. Otherwise it falls back to cloning `ModernRelay/omnigraph-public`
+and building from source.
+
+## Useful Overrides
+
+Install to a different directory:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/install.sh | INSTALL_DIR="$HOME/bin" bash
+```
+
+Force a source build even if a release asset exists:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/install.sh | FORCE_BUILD=1 bash
+```
+
+Build from a specific git ref:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph-public/main/scripts/install.sh | SOURCE_REF=main bash
+```
+
+## Manual Source Build
+
+```bash
+cargo build --release --locked -p omnigraph-cli -p omnigraph-server
+install -m 0755 target/release/omnigraph ~/.local/bin/omnigraph
+install -m 0755 target/release/omnigraph-server ~/.local/bin/omnigraph-server
+```
+
+## Release Assets
+
+Tagged releases are expected to publish:
+
+- `omnigraph-linux-x86_64.tar.gz`
+- `omnigraph-macos-x86_64.tar.gz`
+- `omnigraph-macos-arm64.tar.gz`
+
+Each archive contains both binaries:
+
+- `omnigraph`
+- `omnigraph-server`
+
+## Verify The Install
+
+```bash
+omnigraph version
+omnigraph-server --help
+```