[Nishkarsh1606]

Description

Refactors the v2 docs for brevity and consistent terminology, and replaces the old cookbooks with six short, benchmark-mapped ones.

Cookbooks

• Old cookbooks removed. All v1 and v2 cookbook pages and the tests that executed their code.
• Six new cookbooks under cookbooks/v2/: Glean, Cursor, AI Chief of Staff, personal assistant, competitive intelligence agent, customer support agent. Each is about 100 lines of Python on the v2 API, uses the query settings its benchmark report states, and runs on sample data with only an API key.
• Cookbook home page with a map from each cookbook to the benchmarks on benchmarks.hydradb.com that test it.
• Shared setup lives in snippets/cookbook-setup.mdx and is rendered on every cookbook.
• New test scripts/test_cookbooks.py executes every cookbook against the released SDK's method signatures and the documented payload shapes, with no network. The cookbooks have not been run against the live API.
• Old cookbook URLs redirect to the closest new page.

Rest of the docs

• Every v2 page edited. Get Started, 15 guides, 56 API reference pages, 14 plugin pages, and the agent guide. Each rule is stated once on its owner page and linked elsewhere; "In this guide" lists are gone; endpoint pages no longer restate the schema; BYOG headings are restructured.
• Terminology standard added to CONTRIBUTING.md and applied: class → kind, passage → chunk, item/document → source, allow-list → ACL, recall → query, "your app" → "your application". The Glossary matches it.
• Navigation regrouped by task: Ingest, Query, Organize and Secure, Concepts, Advanced. Error Responses moved into the API Overview group. Site name is "HydraDB".
• Titles: Multi-tenancy → Databases and Collections; How to Use API Results → Use Query Results; MCPs → MCP.
• URL slugs: database endpoint pages no longer say tenant (create-tenant → create-database, and so on), plus multi-tenant → databases-and-collections, sources-overview → context-overview, list-documents → list-context. Every old path has a permanent redirect.

Factual corrections, confirmed with engineering:

• Re-adding an existing connector resource with POST /connectors/{id}/resources returns 409 and changes nothing. Use PATCH to update.
• upsert defaults to true.
• Dashboard links point to dashboard.hydradb.com; plugin links point to v2 pages.

Not in this PR:

• v1 pages are untouched apart from removed cookbook links.
• Code blocks in existing pages are unchanged, so some still use older names (tenant_id= in the CrewAI and LangChain examples, tenant_metadata in two agent-guide examples).
• package.json still lists @hydradb/sdk, typescript, and ts-node, which only the deleted cookbook type-check used.

Open follow-ups, owned by engineering:

• HYDRADB_COLLECTION is required by some plugins and optional in others; the pages describe each plugin as it behaves today.
• failed versus errored as an indexing status; the agent guide tells agents to handle both.

Related Issue

No issue was opened for this work.

Type of Change

• Content fix (typo, broken link, incorrect info)
• New content (guide, tutorial, API docs)
• Structural change (navigation, layout)
• CI/Build

Checklist

• I have read the CONTRIBUTING guidelines
• This PR is linked to an issue
• My commits are signed off (git commit -s) per the DCO
• mintlify dev renders my changes correctly (cookbook home page and Glean page checked; other pages rely on mintlify validate and mintlify broken-links)
• I have not committed any secrets or credentials
• No internal system details are exposed in the content

🤖 Generated with Claude Code

https://claude.ai/code/session_01WY1LUg8AWZayst2djgnjNK

[github-actions]

✅ Mintlify Hygiene

No issues found.

[mintlify]

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

Project	Status	Preview	Updated
cortex-ai	🟢 Ready	View Preview	Nov 11, 2026, 4:24 PM

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

[mintlify]

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

Project	Status	Preview	Updated
cortex-ai	🟡 Building	–	Nov 11, 2026, 2:37 AM

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

[greptile-apps]

Confidence Score: 0/5

[Medium impact] The changes affect the public v2 documentation and the paths readers use to find it.

The PR needs fixes before merging because the new cookbooks can expose private content and fail during their main workflows.

Findings

1.   Private tickets reach other customers ▶
2.   Queries use the wrong permissions ▶
3.  Glean fails while printing citations ▶
4.  Source files fail to upload ▶

Summary

The PR tightens v2 wording, renames database and context pages, and updates navigation and redirects.

• The old cookbook collection is removed while the site keeps a smaller v2 cookbook section.
• V2 navigation and API pages use task groups and database, collection, and context names.
• V2 guides and references use a shared set of names and point readers to the page that owns each rule.
• Plugin pages group setup, configuration, and usage notes into clearer sections.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Six cookbook pages] --> B[Shared Python setup]
  B --> C[Create database and wait]
  C --> D[Ingest sample context]
  D --> E[Wait for indexing]
  E --> F[Query selected collections]
  F --> G[Send context to a model]
  H[Cookbook tests] --> I[Fake API responses]
  I --> A

Loading

_{Reviews (3) · Last reviewed commit: "docs(cookbooks): make the benchmark map ..." · Reviewed by Greptile}

[abhishekt-hydra]

@greptile review please.

[abhishekt-hydra]

@greptile-apps review please