Repository navigation
docs(v2): Guides cleanup (1/3) - #309
Open
SohamRatnaparkhi wants to merge 12 commits into
Open
SohamRatnaparkhi wants to merge 12 commits into
SohamRatnaparkhi wants to merge 12 commits into
Conversation
Rewrite the V2 docs for low cognitive load and correct statements that disagree with the API on main. - Cut pitch, metaphors, repeated summaries, and diagrams that restated lists. Decision tables become bullets; field, status, and error reference tables stay. - Restore product content an earlier draft dropped: the context graph, benchmark numbers, isolation guarantee, connectors, use cases. - API reference landing page lists every endpoint group, including Connectors, Webhooks, Feedback, Subgraph, and Delete Collection. - Fix verified inaccuracies: per-file metadata lives in document_metadata items; memory item metadata is an object; query_apps defaults to true; recency_bias defaults to 0.4; max_results caps at 250; operator and/phrase require query_by text; graph_context false only applies in fast mode; type all reads one scope; envelope exceptions; real error codes. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Shorten V2 pages without dropping facts: merge repeated sections, collapse common-mistakes tables that restated warnings, and replace restatements of other pages with links. Prose is about 23% shorter in the guides and 26% in the cookbooks than on main. Also aligns pages with the API on main: 415 is only for bodies that are neither form nor JSON, dense and sparse metadata lanes are declared at database creation, document_metadata items do not take a title, and the SDK page names its envelope exceptions. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
✅ Mintlify HygieneNo issues found. |
✅ OpenHack SummarySecurity review of docs(v2): Guides cleanup (1/3). 24 changed files; 0 findings at or above the low reporting threshold.
Confidence Score: 5/5No 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
Last reviewed commit: 68f516f · View review on OpenHack
|
![openhack-agent[bot]](https://avatars.githubusercontent.com/in/2637932?s=60&v=4){kind=small}
Contributor
 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
- Internal search cookbook: search() and explain_decision() now fan out across the four source collections unless one is named, so the cross-source flow reads the content it ingested. TypeScript samples use the SDK's camelCase response fields. - Financial analyst cookbook: earnings and board-memo uploads put per-file metadata in document_metadata instead of an extra app_knowledge item. Filter fields go in metadata; labels and event_time go in additional_metadata, which recency ranking reads. Chunks sort by event_time, not upload time. - Webhooks: signing can be enabled at registration with generate_signing_secret or signing_secret, or later on the signing-secret endpoint. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
/query rejects a listed collection that does not exist, and a collection is created on its first write. The internal search cookbook now asks HydraDB which source collections exist (GET /databases/collections) and searches only those, so a reader who wires up one source can search right away. Applies to search() and explain_decision() in Python and TypeScript. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
The provenance modules import source_collections from the qa module, which ran its example query at import time. Guard the examples in qa and provenance (Python and TypeScript) so they run only when the file is executed directly. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Drop documentation for options the API on main does not act on: - enable_match / filterable: the v2 filter path never reads the flag, and no query matches on user metadata fields with it. Removed from guidance, schema field tables, and code samples. A schema field needs only name and data_type; filters match declared metadata fields as before. - Memory item relations: memories[] items have no relations field (the value is never read), so the "Connect related memories" section, field rows, and sample keys are gone. relations on document_metadata and app_knowledge items still work and stay documented. - Memory item expiry_time: no such field exists; rows removed. Also drops the stale claim that schema updates create MongoDB filter indexes, and words vector sync in terms of embedding flags. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
pathToFileURL throws when process.argv[1] is undefined (REPL or node -e), which would make the qa and provenance modules fail to import. Check the argument first. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Review found the rewrite flattened the docs: it cut voice, examples, tables, diagrams, and context. Every V2 page now starts again from its original text on main, with only these changes on top: - Verified factual corrections (defaults, limits, error codes, field shapes, envelope and scoping rules, endpoint behavior). - Code sample bug fixes, including the reviewed cookbook fixes. - Removals requested in review: enable_match/filterable, memory-item relations and expiry_time. - Missing facts added in the original format (for example the endpoint inventory rows for Connectors, Webhooks, Feedback, Subgraph). - Broken links, anchors, and diagram syntax. - Punctuation only: dashes and arrows in prose replaced, bold labels end with a colon, typos fixed. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
SohamRatnaparkhi
changed the title
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
SohamRatnaparkhi
changed the title
This was referenced Oct 5, 2026
Read every Guides page line by line and kept what readers use, cut what repeats or misleads, and fixed statements the code disproves. - Get Started: sharper Introduction (no "substrate", no overclaims), a real mental model in Core Concepts, one Quickstart recap with a correct note on which steps poll. - Usage and Concepts: removed duplicate tables, repeated warnings, and copy-pasted examples; fixed knowledge scoping, memory text/pairs rule, graph_context guidance, metadata prefilter and schema-update claims, field-name rules, and a 500 "safe to retry" contradiction in BYOG. - Glossary now defines the terms the docs use (source, chunk, app source, infer, hybrid, modes, triplet, forceful relations). - Plugins: MCP collection default, legacy tool names, revocation timing, source_id/overwrite, and two missing tools match @hydradb/mcp 1.5.1; CLI drops the unreleased query --title; Claude Code uses current env names. - AGENTS.mdx: mode auto, one-scope rule for type all, metadata guide fixes. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Plugin 1.1.0 reads HYDRADB_DATABASE and HYDRADB_COLLECTION, with the old names as deprecated aliases. Say so, so users on older installs know why the new names are not picked up. Refs PRO-2457 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
Signed-off-by: SohamRatnaparkhi <soham@hydradb.com>
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Removes repetition and jargon from the V2 Guides while keeping the explanations and examples needed to use the product. API Results is in #310; cookbooks are in #311.
Validation: Mintlify build and broken-link checks, MDX/frontmatter compilation, documentation hygiene, Python/JSON example parsing, and agent endpoint verification passed. Published SDK signatures and relevant API behavior were checked. External integrations were not exercised against production.