mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-18 02:24:27 +02:00
c06343362a
Document the per-graph MCP surface (POST /graphs/{id}/mcp, shipped in the
preceding commits and landing under v0.8.0) and the `.gq` authoring controls
that shape stored-query tools.
- New docs/user/operations/mcp.md: the client-facing guide — transport, tool
catalog (built-ins + stored queries), projection modes, structured output,
authorization (call-authoritative + list-relaxation), Host/Origin policy, the
protocol-version contract.
- docs/user/operations/server.md: the /mcp endpoint + an "MCP surface" section;
docs/user/index.md: a "Connect an MCP agent" pointer.
- docs/user/queries/index.md: an Annotations section — query @description /
@instruction / @mcp(expose, tool_name) and per-parameter @description.
- AGENTS.md: topic-table row + MCP note on the HTTP-server capability row.
- docs/dev/testing.md: the omnigraph-mcp crate + server tests/mcp.rs.
- docs/dev/rfc-005 §D5: retire the "cluster = everything exposed" bridge —
cluster mode honors source `@mcp(expose: …)`; presentation vs authorization
split made explicit.
- skills/omnigraph: server-policy.md MCP section; stored-queries.md corrected
(per-query controls now ship via @mcp, not "planned"); SKILL.md MCP triggers,
Deep Dives row, version → 0.8.0.
- docs/releases/v0.8.0.md: the MCP surface + authoring-controls release notes.
Crate version manifests are deliberately NOT bumped — that is the v0.8.0
release-cut step; this lands on the feature branch.
3.3 KiB
3.3 KiB
User Docs
Audience: users, CLI users, HTTP clients, and self-hosting operators
This is the public-facing entry point. These docs describe behavior, commands, configuration, and operational contracts without requiring knowledge of internal recovery mechanics or contributor-only invariants. They are organized by topic — start with install, then follow the section that matches your task.
Start here
| Goal | Read |
|---|---|
| Install OmniGraph | install.md |
| Run the core loop end to end | quickstart.md |
| Understand the model | concepts/index.md |
| Run the CLI | cli/index.md |
| Look up every CLI flag and config field | cli/reference.md |
Schema & queries
| Goal | Read |
|---|---|
Write schemas (the .pg language) |
schema/index.md |
| Read schema-lint diagnostic codes | schema/lint.md |
Write queries (the .gq language) |
queries/index.md |
| Write data — inserts, updates, deletes | mutations/index.md |
| Use vector / full-text / hybrid search | search/index.md |
| Generate embeddings | search/embeddings.md |
| Build and use indexes | search/indexes.md |
Branching & version control
| Goal | Read |
|---|---|
| Work with branches and commits | branching/index.md |
| Read past versions (time travel) | branching/time-travel.md |
| Merge branches and resolve conflicts | branching/merge.md |
| Coordinate multi-query workflows | branching/transactions.md |
| Read diffs and change feeds | branching/changes.md |
Operations
| Goal | Read |
|---|---|
| Deploy the binary or container | deployment.md |
| Use HTTP endpoints | operations/server.md |
| Connect an MCP agent (Claude, Cursor, …) | operations/mcp.md |
| Compact, repair, and clean old versions | operations/maintenance.md |
| Configure Cedar authorization | operations/policy.md |
| Track actors and audit behavior | operations/audit.md |
| Interpret errors and output formats | operations/errors.md |
Clusters
| Goal | Read |
|---|---|
| Deploy and operate a cluster (how-to) | clusters/index.md |
Reference every cluster.yaml key and command |
clusters/config.md |
Concepts & reference
| Goal | Read |
|---|---|
| Understand the model and L1/L2 framing | concepts/index.md |
| Understand graph layout and URI support | concepts/storage.md |
| Look up constants and tunables | reference/constants.md |
Releases
Release notes live in releases/. Use them for user-visible changes between versions, not for contributor design history.
Boundary
User docs focus on stable behavior. If a paragraph needs to explain internal sidecars, Lance API blockers, or test strategy, it probably belongs in docs/dev/index.md or a developer-area document instead.