From 2b901974edddb2280c24afe6637306378f8b7baf Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Mon, 26 Jan 2026 17:25:15 -0800
Subject: [PATCH] chore(release): 7.7.0

---
 CHANGELOG.md      | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 package-lock.json |  4 ++--
 package.json      |  2 +-
 3 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 953401c8..c5ca0c80 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,54 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [7.7.0](https://github.com/soulcraftlabs/brainy/compare/v7.6.1...v7.7.0) (2026-01-26)
+
+### Features
+
+**Match Visibility in Search Results**
+
+Search results now include detailed match information:
+- `textMatches: string[]` - Query words found in entity
+- `textScore: number` - Text match quality (0-1)
+- `semanticScore: number` - Semantic similarity (0-1)
+- `matchSource: 'text' | 'semantic' | 'both'` - Where result came from
+
+```typescript
+const results = await brain.find({ query: 'david the warrior' })
+results[0].textMatches    // ["david", "warrior"]
+results[0].semanticScore  // 0.87
+results[0].matchSource    // "both"
+```
+
+**Semantic Highlighting API**
+
+New `highlight()` method shows which concepts matched:
+
+```typescript
+const highlights = await brain.highlight({
+  query: "david the warrior",
+  text: "David Smith is a brave fighter who battles dragons"
+})
+// Returns both exact matches and semantic concepts:
+// [
+//   { text: "David", score: 1.0, matchType: "text" },
+//   { text: "fighter", score: 0.78, matchType: "semantic" },
+//   { text: "battles", score: 0.72, matchType: "semantic" }
+// ]
+```
+
+**Scalable Word Indexing**
+
+- Increased word limit from 50 to 5000 words per entity
+- Supports articles, chapters, and large documents
+- Roaring Bitmaps provide efficient compression at scale
+
+### Performance
+
+- O(1) fast path in `findMatchingWords()` for text results
+- 500 chunk limit in `highlight()` for memory safety
+- Stopword filtering reduces embedding overhead
+
 ### [7.6.1](https://github.com/soulcraftlabs/brainy/compare/v7.6.0...v7.6.1) (2026-01-26)
 
 - docs: add link to hosted API documentation at soulcraft.com/docs
diff --git a/package-lock.json b/package-lock.json
index a7a32b20..f16dd815 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "7.6.1",
+  "version": "7.7.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@soulcraft/brainy",
-      "version": "7.6.1",
+      "version": "7.7.0",
       "license": "MIT",
       "dependencies": {
         "@aws-sdk/client-s3": "^3.540.0",
diff --git a/package.json b/package.json
index ed507a13..1ac364a3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "7.6.1",
+  "version": "7.7.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",