# AWP Advisor / Search Dependency Decisions

**Date:** 2026-08-20  
**Status:** **BINDING SUPPLEMENT to FOSS/reuse decisions for Advisor + Search capabilities**  
**Related:** `AWP-FOSS-DECISIONS.md`, `AWP-FOSS-SPEC-COVERAGE-MATRIX.md`, `AWP-I0-I1-REUSE-PREFLIGHT.md`

## Decisions

### AS-D1 — `cmdk` is the selected command-palette interaction substrate

Selected target:

```text
dip/cmdk
package: cmdk
current inspected version: 1.1.1
license: MIT
peer React: ^18 or ^19
```

Reasons:

- unstyled/composable React command menu/accessible combobox;
- direct Cmd/Ctrl+K dialog pattern documented upstream;
- local custom filtering available for static commands;
- `shouldFilter={false}` supports externally/server-ranked global results;
- async loading state supported;
- nested command pages are possible;
- no need to rebuild keyboard selection/list/command mechanics.

AWP visual authority remains Astryx/AWP. Preferred integration is `Command` behavior inside the chosen AWP/Astryx dialog/shell primitive when that avoids duplicate dialog styling/focus systems; `Command.Dialog` may be used only if the compatibility/accessibility spike shows it is the simpler correct integration.

### AS-D2 — `cmdk` is NOT the search backend

The upstream architecture keeps/render-filters command items in the React tree. That is appropriate for bounded commands/navigation but not an excuse to preload all AWP entities into the browser.

For global entities:

```text
AWP backend ranks/authorizes results
 -> cmdk shouldFilter=false
 -> render bounded grouped results
```

Full result exploration moves to the URL-restorable Search page.

### AS-D3 — reuse `@platform-modules/search` before custom generic search infrastructure

Current inspected Platform main exposes `@platform-modules/search` version `0.0.5` with:

```text
Hit
SearchProvider
SearchRegistry
SearchParams
SearchGroup
SearchResult
searchEntities(...)
```

and query sanitization through Platform util FTS helpers.

Before writing a generic AWP search registry/cursor/grouping layer, I3 must run a consumer test against the exact Platform revision/version actually consumed.

AWP-specific work remains entity providers, authorization, ranking boosts, result UI, commands and product telemetry.

### AS-D4 — no external search service/vector database baseline

Do not add Elasticsearch/OpenSearch/Meilisearch/Typesense/vector DB merely for AWP command/global search.

Baseline:

```text
PostgreSQL/read-model search
+ Platform search registry/provider seam
```

A specialized service requires measured scale/relevance/semantic-search evidence and an explicit Decision.

### AS-D5 — no generic agent framework becomes Advisor domain authority

Before custom generic model/chat mechanics, inspect:

```text
@platform-modules/ai
@platform-modules/realtime
Astryx AI-chat behavior/primitives
existing AWP Account/Model/Provider and control-surface seams
```

LangGraph/AutoGen/CrewAI/etc. are not baseline domain dependencies merely because AdvisorPersona uses tool-capable model conversations.

The AWP Advisor application/domain owns:

```text
persona/version
scope
thread/context/source references
query grounding
proposal -> canonical command boundary
authorization/audit
```

A provider library may implement a model/tool loop behind this boundary if a later spike proves useful.

### AS-D6 — no separate advisor memory database baseline

Persistent advisor conversation uses AWP/PostgreSQL product state. Canonical Project knowledge remains ProjectVision/Decision/Plan/etc.

Do not add a vector-memory service for “long-term memory” by default. If semantic retrieval over large thread/project corpora becomes a measured need, evaluate it later through the search/provider seam.

## Required Pre-Implementation Proofs

Before I3 Search:

```text
[ ] cmdk + actual AWP React/Astryx integration
[ ] keyboard/focus/dialog/a11y behavior
[ ] server-ranked shouldFilter=false flow
[ ] async loading/no-results/partial failure
[ ] @platform-modules/search consumer test + version pin
[ ] authorization before result/snippet exposure
[ ] realistic large-result bounded palette + full Search pagination
```

Before I3 Project Manager Advisor:

```text
[ ] Platform AI provider helper fit
[ ] Platform realtime/chat helper fit
[ ] persona/thread persistence schema
[ ] page-context envelope + server reauthorization
[ ] source-reference/freshness rendering
[ ] proposal -> canonical Decision/Planning/Task command path
[ ] provider failure/retry/thread preservation
[ ] no secret data in prompt/context/logs
```

## Anti-Rebuild Consequence

Do not implement:

```text
custom command-menu keyboard engine
custom generic search registry/cursor grouping
browser-preloaded global entity index
custom generic provider/model abstraction already supplied by Platform
hidden advisor memory authority
advisor-only mutation pathway
```

without first recording the exact failed reuse/provider proof.