fix(search): one title rule for indexing, prefix and exact search (ENG-3299) by adityamishra-hydradb · Pull Request #336 · hydra-db/mintlify-docs

adityamishra-hydradb · 2026-10-27T23:16:53Z

For humans

Documents the normalized title contract from https://linear.app/hydradb/issue/ENG-3299.

What changed

Defines NFKC normalization, invisible-formatting and decoration removal, lowercase conversion, whitespace collapse, and one known final extension removal.
Documents normalized prefix behavior for list-documents.
Documents normalized exact behavior for query and MCP title filters.
States that source IDs and titles are separate inputs and are never inferred from input shape.

Merge order

Merge after the app change reaches prod.

Related PRs

Application: https://github.com/hydra-db/hydradb-application/pull/2977
Python ingestion fixture and backfill: https://github.com/hydra-db/cortex-ingestion/pull/1150
Documentation: fix(search): one title rule for indexing, prefix and exact search (ENG-3299) #336

For agents

Check that all three surfaces describe the same extension allow-list and the same source-ID-versus-title rule.

Local validation:

npm run hygiene:strict: PASS
npm run verify:agents-endpoints: PASS

Decisions taken without review

I documented only behavior implemented by the paired application and ingestion changes.
I kept notes.v2 and .md as explicit non-stripping examples to define dotted-title edge cases.
I did not document or implement dashboard shape-based inference because ENG-3304 owns that behavior.
I ran validation only on this Vorflux machine. I made no staging or production data call.

Session Details

Session: View Session
Requested by: Aditya Mishra (aditya.mishra@hydradb.com)
Address comments on this PR. Add (aside) to your comment to have me ignore it.

^{Need help on this PR? Tag @codesmith-bot with what you need.}

github-actions · 2026-10-27T23:17:06Z

✅ Mintlify Hygiene

No issues found.

mintlify · 2026-10-27T23:17:20Z

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

Project	Status	Preview	Updated
cortex-ai	🟢 Ready	View Preview	Oct 27, 2026, 11:17 PM

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

adityamishra-hydradb · 2026-10-27T23:17:36Z

@greptileai review

adityamishra-hydradb · 2026-10-27T23:17:37Z

/devin review

openhack-agent · 2026-10-27T23:17:41Z

✅ OpenHack Summary

Security review of fix(search): one title rule for indexing, prefix and exact search (ENG-3299). 3 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

api-reference/v2/endpoint/list-documents.mdx (modified)
api-reference/v2/endpoint/query.mdx (modified)
plugins/mcp.mdx (modified)

Last reviewed commit: b8dac9c · 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.

devin-ai-integration · 2026-10-27T23:17:42Z

Starting Devin Review.

openhack-agent

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

devin-ai-integration

Devin Review found 1 potential issue.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

devin-ai-integration · 2026-10-27T23:18:45Z

DCO check

 | <Field name="collections" type="string[] or object" /> | Multi-collection scope. Send a list of collection IDs for equal weighting, or an object mapping collection ID to a positive relative weight (at most one decimal place, e.g. `{"finance": 1.5, "legal": 0.8}`) to bias ranking. Up to 100 collections. Do not combine with `collection`. |
 | <Field name="query" type="string" required /> | Query terms or natural-language question. Cannot be empty. Maximum 5,000 words. |
-| <Field name="titles" type="string[]" /> | Exact source titles, matched case-insensitively. Matches any listed title, then intersects with `ids` if both are sent. |
+| <Field name="titles" type="string[]" /> | Exact normalized source titles. Normalization applies Unicode NFKC, removes invisible marks and decoration, lowercases, collapses spaces, and removes one final known file extension (`md`, `markdown`, `txt`, `pdf`, `doc`, `docx`, `rtf`, `odt`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `tsv`, `json`, `html`, or `htm`) when text remains before it. Matches any listed title, then intersects with `ids` if both are sent. Use `ids` for source IDs and `titles` for titles; HydraDB never guesses from the input format. |


🟡 Unsigned commit blocks the DCO check

The commit adding this title contract lacks a Signed-off-by trailer. The required DCO check fails, blocking the PR.

Learn more

Every PR commit must carry a Developer Certificate of Origin sign-off. The only commit in this PR has no Signed-off-by trailer, and the DCO check rejects any unsigned commit. Editing documentation text cannot fix the commit metadata.

Example: The check scans b8dac9c, finds no trailer, and exits with an error even if documentation validation passes.

Recommended fix: Amend the commit with git commit --amend -s --no-edit using a valid signing identity, then push the updated commit.

Was this helpful? React with 👍 or 👎 to provide feedback.

Replaced by signed commit 8da3cf1 on #337. PR 336 is closed to avoid rewriting published history.

greptile-apps · 2026-10-27T23:20:32Z

Confidence Score: 4/5

[Low impact] The PR updates documentation for three title-search inputs.

The documentation appears safe to merge after the stated application rollout, with two non-blocking documentation gaps.

Findings

OpenAPI omits the new rule ▶
Source-ID guidance leaves users guessing ▶

Summary

Documents one normalized title rule across list, query, and MCP search.

Search docs use one title cleanup rule across list, query, and MCP.

_{Reviews (1) · Last reviewed commit: "docs(search): define normalized title ma..." · Reviewed by Greptile}

greptile-apps · 2026-10-27T23:20:35Z

 | <Field name="collections" type="string[] or object" /> | Multi-collection scope. Send a list of collection IDs for equal weighting, or an object mapping collection ID to a positive relative weight (at most one decimal place, e.g. `{"finance": 1.5, "legal": 0.8}`) to bias ranking. Up to 100 collections. Do not combine with `collection`. |
 | <Field name="query" type="string" required /> | Query terms or natural-language question. Cannot be empty. Maximum 5,000 words. |
-| <Field name="titles" type="string[]" /> | Exact source titles, matched case-insensitively. Matches any listed title, then intersects with `ids` if both are sent. |
+| <Field name="titles" type="string[]" /> | Exact normalized source titles. Normalization applies Unicode NFKC, removes invisible marks and decoration, lowercases, collapses spaces, and removes one final known file extension (`md`, `markdown`, `txt`, `pdf`, `doc`, `docx`, `rtf`, `odt`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `tsv`, `json`, `html`, or `htm`) when text remains before it. Matches any listed title, then intersects with `ids` if both are sent. Use `ids` for source IDs and `titles` for titles; HydraDB never guesses from the input format. |


OpenAPI omits the new rule

The new title rule is missing from api-reference/v2/openapi.json. Its titles description still mentions only case-insensitive matching, and its list-title description mentions only case-insensitive prefix matching. Readers of that contract miss how extensions, Unicode, and spacing affect matches. Update those descriptions alongside these pages.

Addressed on replacement PR #337 in 668cb7c, with OpenAPI description sources updated in application commit 680b9a57d. PR 336 is closed.

greptile-apps · 2026-10-27T23:20:35Z

+Source IDs and titles are separate inputs. Use `ids` for source IDs and `titles`
+for titles. HydraDB never guesses from the input format.


Source-ID guidance leaves users guessing

This new instruction tells users to pass ids inside the hydradb_query section, but that tool's parameter table does not list ids, and its example only shows titles. Document the supported source-ID input here, or name the tool users should call instead. Otherwise users must guess how to follow the new guidance.

Addressed on replacement PR #337 in 668cb7c. The MCP-specific source-ID guidance now names the supported tools. PR 336 is closed.

adityamishra-hydradb · 2026-10-27T23:22:19Z

Replaced by #337 because the original pushed commit lacked the required DCO sign-off. The replacement branch preserves the changes with a signed-off commit and avoids a force-push.

mintlify · 2026-10-27T23:25:42Z

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

Project	Status	Preview	Updated
cortex-ai	🟡 Building	–	Oct 27, 2026, 11:16 PM

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

docs(search): define normalized title matching (ENG-3299)

b8dac9c

vorflux Bot assigned adityamishra-hydradb Oct 27, 2026

mintlify Bot deployed to staging October 27, 2026 23:17

View deployment

openhack-agent Bot reviewed Oct 27, 2026

View reviewed changes

adityamishra-hydradb mentioned this pull request Oct 27, 2026

fix(search): one title rule for indexing, prefix and exact search (ENG-3299) #337

Open

devin-ai-integration Bot reviewed Oct 27, 2026

View reviewed changes

greptile-apps Bot reviewed Oct 27, 2026

View reviewed changes

adityamishra-hydradb closed this Oct 27, 2026

		Source IDs and titles are separate inputs. Use `ids` for source IDs and `titles`
		for titles. HydraDB never guesses from the input format.

Conversation

adityamishra-hydradb commented Oct 27, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

For humans

What changed

Merge order

Related PRs

For agents

Decisions taken without review

Uh oh!

github-actions Bot commented Oct 27, 2026

✅ Mintlify Hygiene

Uh oh!

mintlify Bot commented Oct 27, 2026

Uh oh!

adityamishra-hydradb commented Oct 27, 2026

Uh oh!

adityamishra-hydradb commented Oct 27, 2026

Uh oh!

openhack-agent Bot commented Oct 27, 2026

✅ OpenHack Summary

Confidence Score: 5/5

Uh oh!

devin-ai-integration Bot commented Oct 27, 2026

Uh oh!

openhack-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

adityamishra-hydradb Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Uh oh!

greptile-apps Bot Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

adityamishra-hydradb Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

adityamishra-hydradb Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

adityamishra-hydradb commented Oct 27, 2026

Uh oh!

mintlify Bot commented Oct 27, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

adityamishra-hydradb commented Oct 27, 2026 •

edited by devin-ai-integration Bot

Loading

greptile-apps Bot commented Oct 27, 2026 •

edited

Loading