docs(v2): Guides cleanup (1/3)

[SohamRatnaparkhi]

Reworks the V2 Guides so a first-time developer can follow them: every page opens with what the thing is and the call that uses it, shows one concrete request with a table explaining each property, then builds up the concepts in the order a developer meets them. Code is collapsed behind Python, TypeScript, or cURL accordions, so the first screen shows the choices rather than code. This is the shape that landed in App Sources (#315). API Results is in #310; cookbooks are in #311.

Navigation: Get Started (Introduction, Quickstart, Core Concepts), then Usage with Ingestion (Knowledge, App Sources, Memories, Connectors, Webhooks), Retrieve, and Bring Your Own Graph, then Organize, Understand, Integrations, Plugins, and For Agents. The two Bring Your Own Graph pages are merged into one, carried over from #304, and Custom Ingestion Instructions is folded into Connectors; both old URLs redirect.

Page by page:

• Introduction: "the unified context engine for AI". What HydraDB is, how you get it back, the full benchmark set, what else HydraDB has (connectors with access control, SDKs, tools), what you can build, get started. The Quickstart is linked at the top.
• Core Concepts: three terms: Database (with collections inside), Context (knowledge, memory, app source), Query (with the context graph inside). Adds the company-brain guidance: one collection for everything, with metadata filters and access control for isolation.
• Quickstart: builds a context layer with both knowledge and a memory, then one type: "all" query over both collections. Restores "What you have built".
• Knowledge: upload files, ingest app sources, wait for indexing, retrieve, metadata, forceful relations, field reference. App sources point to the App Sources guide. Relation targets use target.source_id and the example sends relations.ids, which is what returns linked text.
• Memories: save, scope to one user, infer, input shapes, retrieve, update or delete, field reference.
• Connectors: four-call setup first, with Python, TypeScript, and cURL for every call (checked against SDK 2.1.7 and a mock server), then status, changing a connector, custom ingestion instructions, metadata, permissions, several accounts. Names the live provider catalog (70 on production).
• Query: one request with a response walkthrough, recipes, tuning, scope, relationships, acl, parameter reference. Every default re-verified against the backend.
• Semantic Search and Context Graphs: open with what the reader can do; duplicate Query material removed.
• Multi-tenancy: one user's collection on ingest and query first; patterns; how scoping works; the legacy field migration last.
• Metadata: declare a field, ingest with it, filter on it; operator caveats are plain labeled paragraphs rather than warning boxes; then the two layers, operators, limits, adding fields, updating metadata, listing. Drops the searchable schema flag, which the backend treats as a no-op.
• Access Control: set an ACL and query as the caller first, with a worked example of which documents each query acl returns; principals; connector capture; change or revoke. Corrects the claim that uploaded files take acl at ingest; only app source items do, and any source can get one through the metadata PATCH. No longer points readers at rbac_support on the providers endpoint, which is always false there.
• Webhooks: register first, then the payload, signature verification, deliveries and retries, signing secret rotation. 35 expanded code blocks become 11 collapsed accordions; every table and verified fact kept.
• Architecture and Glossary: repetition with Query and Metadata removed; Glossary adds Class.
• Plugins: Claude Code documents the plugin version that reads the new env names.
• AGENTS.mdx: metadata placement, memory metadata as an object, envelope exceptions, retries cover 502.

Latest pass, applying the review principles to the remaining pages:

• Query is back near main's length (1,763 words, from 2,904): tuning, scope, and relationships are short bullets with every default kept, and the parameter reference that repeated them is replaced by a link to the API reference.
• Multi-tenancy leads with choosing a scope, with the company brain (one collection, metadata filters and ACLs for isolation) as the default.
• Glossary keeps only HydraDB terms, grouped as Database, Context, and Query like Core Concepts.
• Connectors and Connector Instructions lose repeated explanations; no page uses the "one user" or "material it answers from" wording.

Agent-friendliness and merge, 2026-10-09:

• Quickstart: a Prompt card (Copy prompt, Open in Cursor) hands the integration to a coding agent, pointing it at AGENTS.md.
• AGENTS.md: new access control rule and section (a query without acl is unfiltered), a connectors section with verified Python and TypeScript, company-brain scoping in place of the old "metadata filters are not a substitute for collections" rule, one method table for all 44 public methods, and a note on the SDKs' built-in retries.
• Merged with main after docs(plugins): consolidate plugins into five pages #312 (plugin consolidation). Claude Code keeps the verified HYDRADB_API_KEY (the plugin's canonical name; HYDRA_DB_API_KEY is a deprecated alias), so the Codex section no longer says the two plugins use different key names.

Integrations, 2026-10-09: in V2, Integrations lists MCP and CLI first. A separate Plugins heading lists Hermes, OpenClaw, CrewAI, LangChain, Claude Code, Codex, Cursor, OpenCode, Muse Code, and Grok Build directly, without nested categories. Every plugin has its own page with its content as written and a repo link. The shared modes and config variables stay on the Claude Code page, and the other engine plugins link there. The old Ecosystem URL is retained as a compact link page with its original section headings, preserving fragment bookmarks for the individual setup guides.

Source and support, 2026-10-09: every integration page, including MCP and CLI, ends with a Feedback and contributions heading and a short sentence linking directly to its GitHub issue tracker and repository. Cards are removed; package installation stays in the setup instructions. The Hermes pip tab installs from GitHub, since hydradb-hermes is not on PyPI.

Review fixes, 2026-10-09: Bring Your Own Graph keeps main's note that deleting a standard-created database drops only its graph collections and returns deleted: false (checked in the backend), gets a runnable KEY placeholder, and says the migration script copies one label and one relationship type. The Quickstart checklist follows the walkthrough order, its agent prompt asks the reader to set the API key rather than paste it, and Query caching expires entries when permissions change.

Removed everywhere because the code ignores them: enable_match, filterable, memory relations, memory expiry_time.

This branch is merged with main after #315, and the App Sources page is identical to main.

Validation: Mintlify build validation, broken links, hygiene (including anchors), MDX compile, label and dash checks all pass. Facts were verified against the backend on main, the Python SDK 2.1.5, and the TypeScript SDK 2.1.7.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cortex-ai	🟢 Ready	View Preview	Oct 9, 2026, 9:48 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

✅ Mintlify Hygiene

No issues found.

[openhack-agent]

✅ OpenHack Summary

Security review of docs(v2): Guides cleanup (1/3). 37 changed files; 0 findings at or above the low reporting threshold.

0   0   0   0

Confidence Score: 5/5

No reportable security findings were detected in this scan.

Security merge-readiness rubric: 1 = critical, 2 = high, 3 = medium, 4 = low, 5 = no reportable findings. This score reflects scan findings, not a guarantee of correctness or complete coverage.

Files Needing Attention: None

Important Files Changed

• AGENTS.mdx (modified)
• api-reference/v2/endpoint/create-connector.mdx (modified)
• api-reference/v2/endpoint/update-connector-resource.mdx (modified)
• api-reference/v2/endpoint/update-connector.mdx (modified)
• docs.json (modified)
• essentials/v2/access-control.mdx (modified)
• essentials/v2/architecture.mdx (modified)
• essentials/v2/bring-your-own-graph.mdx (modified)
• essentials/v2/connector-instructions.mdx (removed)
• essentials/v2/connectors.mdx (modified)
• essentials/v2/context-graphs.mdx (modified)
• essentials/v2/glossary.mdx (modified)
• essentials/v2/graph-collections-byog.mdx (removed)
• essentials/v2/knowledge.mdx (modified)
• essentials/v2/memories.mdx (modified)
• essentials/v2/metadata.mdx (modified)
• essentials/v2/multi-tenant.mdx (modified)
• essentials/v2/query.mdx (modified)
• essentials/v2/semantic-search.mdx (modified)
• essentials/v2/webhooks.mdx (modified)
• get-started/v2/core-concepts.mdx (modified)
• get-started/v2/introduction.mdx (modified)
• get-started/v2/quickstart.mdx (modified)
• mintlify-hygiene.toml (modified)
• plugins/claude-code.mdx (modified)

View all 37 changed files

Last reviewed commit: bf0bc95 · View review on OpenHack

---

TIP: Mention @openhack-agent in a PR comment to request a review or ask a question. Use @openhack-agent fix all for every finding, or @openhack-agent fix unresolved threads for open review threads only.

[openhack-agent]

OpenHack reviewed this commit. See the OpenHack Summary for the confidence score and fix actions.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge; no new actionable issue was established in the changes since the previous review.

Summary

The PR reorganizes the V2 Guides around onboarding and task-focused examples, consolidates connector and graph guidance, and expands the agent integration reference. The latest change places agent and coding guides in a separate V2 Plugins sidebar group while retaining MCP and CLI under Integrations.

_{Reviews (35) · Last reviewed commit: "docs(v2): list plugins under a single si..." · Reviewed by Greptile}

[SohamRatnaparkhi]

Please reassess the remaining findings against 32cce60:

• Ecosystem bookmarks: /plugins/ecosystem is retained with every original heading and links to the corresponding individual setup guide. The broad OpenClaw redirect is removed.
• Package links: CrewAI and LangChain link to PyPI beside their installation commands; OpenCode links to npm in its installation step. The user-approved contribution footer stays card-free.
• TypeScript fields: the exact Metadata, Webhooks, and Query examples were executed through the published @hydradb/sdk 2.1.7 with a mocked transport. The SDK accepts databaseMetadataSchema, nested dataType, eventTypes, generateSigningSecret, and maxResults; it serializes them to snake_case on the wire. It deserializes source_title and chunk_content to sourceTitle and chunkContent. Changing those SDK fields to snake_case would drop them. The contradictory SDK-reference prose is corrected in API PR docs(v2): API reference and response corrections (2/3) #310, per the requested Guides/API/Cookbooks split. Published source: https://registry.npmjs.org/@hydradb/sdk/-/sdk-2.1.7.tgz.
• MCP ordering: Agent frameworks, Coding agents, MCP, CLI is the user-approved order and the current PR description. Both nested groups open by default. The earlier MCP-first proposal is superseded.

Mintlify build validation and hygiene pass. All legacy Ecosystem headings were compared with main, and each retained package link is outside the contribution footer.