> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_28/session_11_search_palette_and_deterministic_embeddings.md).

# Session 11: Search Palette And Deterministic Embeddings

**Session ID**: `phase28-session11-search-palette-and-deterministic-embeddings` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add an extension-local search command palette over the already-loaded payload, and ship the dependency-free feature-hash embeddings the Phase 27 Session 11 ADR deferred -- using them for palette result ranking (client-side), theme-rollup grouping (collect-time), and replacing the weakest fallback path (group-by-source clustering) with similarity clustering. This resolves the Phase 27 embedding decision.

***

## Source Mapping (from the Trends-Finderz improvement map, items 8.1 and 8.2)

### Cross-view search command palette (item 8.1)

* **Trends-finderz:** a global palette (Ctrl/Cmd+K, `/` to open, Enter for best result, Esc) searches trend names, canonical keys, aliases, categories, source names, evidence titles, and creator angles, with scope and window filters.
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/components/search/SearchCommandPalette.tsx` (711 lines; README "Search" section in `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/README.md`)
* **Trend Finder today:** search exists only as the Workbench text filter (`src/extensions/trend-finder/signal-workbench-model.ts`); Trends, Hidden Gems, Watchlist, and Brief have no search, and nothing jumps from a query to a topic across views.
* **Improvement:** an extension-local palette over the already-loaded payload (topics, aliases, evidence titles, angles, source names) that navigates to the owning view and selects the topic. Client-side only; the payload is already in memory; no new data surface.
* **Implement in:** new `src/extensions/trend-finder/components/trend-search-palette.tsx` + a small index builder in `src/extensions/trend-finder/view-model.ts`; mounted in the extension shell (`src/extensions/trend-finder/client.tsx`); keyboard handling must respect the host's existing shortcuts and reduced-motion conventions.

### Dependency-free deterministic embeddings (item 8.2)

* **Trends-finderz:** "semantic" search needs no model: 384-dim vectors built by SHA-256 feature hashing over tokens, soft stems, curated synonym expansions, bigrams/trigrams, and character 4-grams, L2-normalized, combined with lexical ranking and product-relevance boosts into a hybrid score, with graceful fallback to pure lexical when the vector index is unavailable.
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/search/semantic-vector.ts`
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/search/server-dashboard-search.ts`
  * `/home/aiwithapex/projects/aios/EXAMPLES/trends-finderz/lib/search/dashboard-search.ts`
* **Trend Finder today / reconciliation:** Phase 27 Session 11 deferred embedding-based fallback clustering as investigate-only because "a local embedding model is a new dependency that needs its own decision." Feature-hash embeddings resolve that blocker: pure stdlib, deterministic, testable. This session ships them.
* **Improvement (three uses, ascending ambition):**
  1. rank palette results from item 8.1 (cosine + lexical hybrid, client-side);
  2. group related topics for the Phase 27 theme rollups (cosine threshold over topic vectors at collect time), strengthening the keyword-overlap fallback;
  3. replace the weakest fallback path -- group-by-source clustering -- with similarity clustering over evidence titles when AI is unavailable.
* **Implement in:** shared helper (collector-side `scripts/lib/ai-runtime/text-vectors.ts` with a mirrored client util or a shared module under `src/lib/`), consumers per use case (`scripts/extensions/trend-finder/topics.ts` for fallback clustering).
* **Constraints:** do not ship 384-float arrays per topic in the browser payload (size); compute client-side from text for UI uses, collector-side for clustering uses. Synonym tables are domain config and belong next to the keyword packs from Session 13.

***

## Scope

### In Scope (MVP)

* `trend-search-palette.tsx` over the in-memory payload (names, canonical keys, aliases, categories, source names, evidence titles, angles) with open/navigate/select keyboard handling that respects host shortcuts and reduced motion
* A small index builder in `view-model.ts`
* `text-vectors.ts` SHA-256 feature-hash embeddings (stdlib, deterministic, L2-normalized) with cosine + lexical hybrid scoring and pure-lexical fallback
* Palette ranking via the hybrid score (client-side, computed from text)
* Collect-time cosine grouping to strengthen the Phase 27 theme-rollup fallback
* Similarity-based fallback clustering in `topics.ts` replacing group-by-source when AI is unavailable
* Tests: embedding determinism, cosine grouping, palette ranking, lexical fallback, no 384-float arrays in the payload

### Out of Scope

* Shipping any embedding-model dependency or vector database (explicitly avoided; stdlib only)
* Persisting vectors in the browser payload (size)
* Changing how the analyst clusters evidence into topics in AI mode

***

## Prerequisites

* [ ] Phase 27 Session 11 theme rollups present (clustering consumer)
* [ ] Session 10 completed (palette can navigate to pinned topics and tags)

***

## Deliverables

1. `trend-search-palette.tsx` and a `view-model.ts` index builder
2. `text-vectors.ts` feature-hash embeddings with hybrid + lexical-fallback scoring
3. Palette ranking, collect-time theme grouping, and similarity fallback clustering
4. A written resolution of the Phase 27 embedding ADR (ship feature-hash, no model dependency)
5. Tests for determinism, grouping, ranking, fallback, and payload-size safety

***

## Success Criteria

* [ ] The palette opens on the host shortcut, searches across the loaded payload, and navigates to the owning view with the topic selected
* [ ] Embeddings are pure stdlib, deterministic, and never ship as float arrays in the browser payload
* [ ] Theme-rollup fallback grouping improves over keyword-overlap alone; AI-mode clustering is unchanged
* [ ] Fallback clustering uses text similarity instead of group-by-source
* [ ] The Phase 27 embedding ADR decision is resolved in writing
* [ ] Existing tests pass; reduced-motion and host shortcuts are respected


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_28/session_11_search_palette_and_deterministic_embeddings.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.