docs(user): add task guides — hybrid search, cluster on S3, review workflow (Phase 3b)

[aaltshuler]

Phase 3b of the docs restructure — task-oriented guides. Docs only.

Four new pages under docs/user/guides/, each a runnable, code-verified
command sequence:

• hybrid-search.md — schema with an @embed vector + text body, load, then
  a query fusing bm25 and nearest with rrf. Notes that indexes are
  engine-maintained (no manual build step).
• cluster-on-s3.md — cluster.yaml with a storage: s3:// root, the
  validate→import→plan→apply flow, loading via the graph's storage URI, and
  config-free serving with omnigraph-server --cluster s3://….
• review-workflow.md — load onto a branch with --from, inspect with
  --branch reads / commit list, merge with --into, then delete + cleanup.
• index.md — the section landing page.

Every command was checked against crates/omnigraph-cli/src/cli.rs — e.g. caught
that load has no --cluster/--cluster-graph (those are storage-plane
only) and used the positional storage URI instead.

Wired into docs/user/index.md (new Guides section) and AGENTS.md's topic table.

Verification

• Zero broken .md links.
• scripts/check-agents-md.sh green (61 links, 58 docs).

This completes the docs restructure (Phase 1 #223 · Phase 2 #225 · Phase 3a #226 ·
Phase 3b here). Remaining follow-up tracked separately: the website
import-docs.mjs subdir-aware update before the next site re-sync.

🤖 Generated with Claude Code

Greptile Summary

Phase 3b of the docs restructure adds four new pages under docs/user/guides/ — hybrid search, cluster-on-S3, branch-based review workflow, and a section landing page — plus wiring in docs/user/index.md and AGENTS.md.

• hybrid-search.md and cluster-on-s3.md: commands verified against cli.rs; omnigraph query (not the deprecated read alias), correct --store global flag, and valid positional URIs for init/load are all used correctly.
• review-workflow.md: all four branch subcommand examples (branch list, branch create, branch merge, branch delete) pass the graph path as a bare trailing positional, but every BranchCommand variant declares uri as #[arg(long)] — not a positional — so clap will reject these invocations. The fix is --store graph.omni in place of the trailing positional; the same mis-pattern also exists in AGENTS.md line 228 and should be corrected there in the same pass.

Confidence Score: 4/5

Safe to merge after fixing the branch command syntax in review-workflow.md (and the matching AGENTS.md line); the other two guides are correct.

Two out of three new guides (hybrid-search.md, cluster-on-s3.md) are accurate against the CLI source. The third (review-workflow.md) documents four branch commands with a trailing positional URI that clap will reject — every BranchCommand variant has uri as a named --uri/--store flag, not a positional slot. A user following the guide step-by-step will hit an error on the very first branch list invocation.

docs/user/guides/review-workflow.md — all branch command examples need --store graph.omni instead of the trailing positional; also AGENTS.md line 228 carries the same issue for branch merge.

Important Files Changed

Filename	Overview
docs/user/guides/review-workflow.md	New guide for branch-based review workflow; all four branch subcommand invocations use trailing positional URIs that clap will reject — the uri field is #[arg(long)] in every BranchCommand variant, so --store is required instead.
docs/user/guides/hybrid-search.md	New end-to-end hybrid search guide; uses omnigraph query (not the deprecated read alias) with correct --store flag and valid positional for init/load; commands verified against cli.rs.
docs/user/guides/cluster-on-s3.md	New cluster-on-S3 guide; validate/import/plan/apply use correct --config flag, load uses a positional URI (valid for Load), maintenance commands correctly use global --cluster + --graph flags.
docs/user/guides/index.md	Simple landing page listing the three new guides with correct relative links; no issues found.
docs/user/index.md	Adds a Guides section table with links to the three new guides; links are correct relative paths.
AGENTS.md	Adds one row to the topic table pointing to the new guides index; wiring is correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User] --> B{Task}
    B -->|Hybrid search| C[omnigraph init --schema schema.pg docs.omni]
    C --> D[omnigraph load --data docs.jsonl --mode overwrite docs.omni]
    D --> E[omnigraph query --query queries.gq hybrid --store docs.omni]

    B -->|Cluster on S3| F[omnigraph cluster validate/import/plan/apply --config company-brain]
    F --> G[omnigraph load --data seed.jsonl s3://bucket/cluster/graphs/knowledge.omni]
    G --> H[omnigraph-server --cluster s3://bucket/cluster]

    B -->|Review workflow| I[omnigraph load --branch review/... --from main --store graph.omni]
    I --> J[omnigraph query --branch review/... --store graph.omni]
    J --> K{Looks good?}
    K -->|Yes| L[omnigraph branch merge ... --into main --store graph.omni]
    K -->|No| I
    L --> M[omnigraph branch delete ... --store graph.omni]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User] --> B{Task}
    B -->|Hybrid search| C[omnigraph init --schema schema.pg docs.omni]
    C --> D[omnigraph load --data docs.jsonl --mode overwrite docs.omni]
    D --> E[omnigraph query --query queries.gq hybrid --store docs.omni]

    B -->|Cluster on S3| F[omnigraph cluster validate/import/plan/apply --config company-brain]
    F --> G[omnigraph load --data seed.jsonl s3://bucket/cluster/graphs/knowledge.omni]
    G --> H[omnigraph-server --cluster s3://bucket/cluster]

    B -->|Review workflow| I[omnigraph load --branch review/... --from main --store graph.omni]
    I --> J[omnigraph query --branch review/... --store graph.omni]
    J --> K{Looks good?}
    K -->|Yes| L[omnigraph branch merge ... --into main --store graph.omni]
    K -->|No| I
    L --> M[omnigraph branch delete ... --store graph.omni]

Loading

_{Reviews (2): Last reviewed commit: "docs(user): add task guides — hybrid sea..." | Re-trigger Greptile}

[greptile-apps]

omnigraph read is a deprecated alias — guides should use omnigraph query

The CLI renamed read to query in v0.6.0 (docs/releases/v0.6.0.md). The read spelling remains as a visible_alias but prints a one-line deprecation warning to stderr on every invocation, and the CLI reference explicitly says "New integrations should target the canonical names." A guide that is the first thing users touch should not immediately trigger a deprecation warning that suggests they're doing something wrong.

Same issue appears in review-workflow.md line 34.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Non-mock path is missing the compiler-side API key required for nearest()

The guide configures only GEMINI_API_KEY (engine-side ingest client), but the mock comment itself discloses that two clients are active: OMNIGRAPH_EMBEDDINGS_MOCK=1 covers the engine-side and NANOGRAPH_EMBEDDINGS_MOCK=1 covers the compiler-side (query-time normalization via the NanoGraph/OpenAI client). When running against a real provider the corresponding real credentials are also needed on both sides. A user who copies just export GEMINI_API_KEY=... will succeed at load but then fail at runtime when vector_search or hybrid tries to embed $q. The fix is to add OPENAI_API_KEY=... (or OPENAI_BASE_URL / NANOGRAPH_EMBED_MODEL for a self-hosted OpenAI-compatible endpoint) to the real-credentials example, or at minimum call out the two-client requirement inline rather than deferring entirely to the embeddings reference link.

[greptile-apps]

Use the canonical omnigraph query command; omnigraph read is a deprecated alias since v0.6.0 and prints a stderr warning on every invocation.

Suggested change

	omnigraph read --query queries.gq --name hybrid \
	--params '{"q":"trends in AI safety"}' --format table docs.omni
	omnigraph query --query queries.gq --name hybrid \
	--params '{"q":"trends in AI safety"}' --format table docs.omni

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Use the canonical omnigraph query command; omnigraph read is a deprecated alias since v0.6.0 and prints a stderr warning on every invocation. The cookbooks and cli/reference.md both use omnigraph query.

Suggested change

	omnigraph read --query checks.gq --name count_by_type \
	--branch review/2026-04-25 --format table graph.omni
	omnigraph query --query checks.gq --name count_by_type \
	--branch review/2026-04-25 --format table graph.omni

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

The real-credentials path should surface both API keys. The mock comment already reveals that two clients are active — OMNIGRAPH_EMBEDDINGS_MOCK for the engine (ingest-time @embed) and NANOGRAPH_EMBEDDINGS_MOCK for the compiler (query-time text-to-vector for nearest()). Without an OpenAI-compatible key, any query that passes a string to nearest() will fail at runtime even if load succeeded.

Suggested change

	export GEMINI_API_KEY=... # ingest-time document embeddings
	# For local experimentation without a provider, deterministic mock vectors:
	# export OMNIGRAPH_EMBEDDINGS_MOCK=1 NANOGRAPH_EMBEDDINGS_MOCK=1
	export GEMINI_API_KEY=... # engine-side: ingest-time @embed (RETRIEVAL_DOCUMENT)
	export OPENAI_API_KEY=... # compiler-side: query-time nearest() normalization (RETRIEVAL_QUERY)
	# For a self-hosted OpenAI-compatible endpoint: OPENAI_BASE_URL=... NANOGRAPH_EMBED_MODEL=...
	# For local experimentation without a provider, deterministic mock vectors:
	# export OMNIGRAPH_EMBEDDINGS_MOCK=1 NANOGRAPH_EMBEDDINGS_MOCK=1

[aaltshuler]

Rebased onto current main (was CONFLICTING — the two wiring files) and re-verified every command against today's cli.rs, aligning with 0.8.0. Four content fixes in the re-verification pass:

• omnigraph read --name <q> → omnigraph query <q> (canonical verb post-RFC-011; read is a deprecated alias, and the query name is positional — there is no --name flag) with --store <uri> instead of a positional URI (query takes no positional store) — in both hybrid-search and review-workflow.
• Dropped NANOGRAPH_EMBEDDINGS_MOCK (no longer exists in source; OMNIGRAPH_EMBEDDINGS_MOCK is the only mock switch).
• --cluster-graph → --graph in the maintenance commands (the flag is the global --graph).
• Added omnigraph repair to the cluster maintenance section (new since the PR was written).

Re-verified as still correct: load flags + fork-with---from semantics, branch create/merge/delete, commit list --branch, cluster validate/import/plan/apply --config, storage: + applies_to in cluster.yaml, the derived graphs/<id>.omni roots, OMNIGRAPH_SERVER_BEARER_TOKENS_JSON, and the .gq shapes (score-as-column + order { score desc } matches docs/user/search/index.md's documented contract). check-agents-md.sh green (69 links, 66 docs).