feat: add knowledge base suggestion core

tools/v2/team/knowledge-base-suggestion/README.md

@@ -1,15 +1,129 @@
 # Knowledge Base Suggestion
 
-This folder is the isolated workspace for the Knowledge Base Suggestion tool.
+Folder-local V2 team tool for suggesting internal knowledge base articles from a
+support or team-mail context.
+
+This contribution implements the isolated core feature engine only. It does not
+wire the tool into the main app, inbox, routing, database, wallet, Stellar
+integration, or design system.
 
 ## Ownership Boundary
 
 All work for this tool must stay inside:
 
-`text
-.\tools\v2\team\knowledge-base-suggestion\
-`
+```
+tools/v2/team/knowledge-base-suggestion/
+```
+
+Do not wire this tool into the main app, routing, inbox architecture, wallet core,
+Stellar integration, database schema, or design system unless a future integration
+issue explicitly allows it.
+
+## Folder Structure
+
+```
+knowledge-base-suggestion/
+  docs/
+    contract.md                         API, states, fixtures, limitations
+  fixtures/
+    knowledge-base-fixtures.json        Synthetic article and request data
+  services/
+    knowledge-base-suggestion.service.mjs
+                                         Pure validation, scoring, and state logic
+  tests/
+    knowledge-base-suggestion.test.mjs  Node built-in tests
+  index.mjs                             Folder-local public API
+  README.md
+  specs.md
+```
+
+## Setup
+
+No install step is required. The service and tests use Node built-ins only.
+
+Requirements:
+
+- Node 18 or later.
+- Run commands from the repository root unless noted otherwise.
+
+## Running Tests
+
+From the repository root:
+
+```
+node --test tools/v2/team/knowledge-base-suggestion/tests/knowledge-base-suggestion.test.mjs
+```
+
+From this folder:
+
+```
+node --test tests/knowledge-base-suggestion.test.mjs
+```
+
+## Core API
+
+The folder-local API is exported from `index.mjs`:
+
+- `suggestKnowledgeBaseArticles(input, options)` returns a deterministic
+  `success` or `empty` state with ranked suggestions.
+- `scoreKnowledgeBaseArticle(article, request)` returns scoring details for one
+  article and one validated request.
+- `validateSuggestionRequest(input)` validates and sanitizes request input.
+- `validateKnowledgeBaseArticle(article)` validates local article fixture shape.
+- `createLoadingState(query)`, `createEmptyState(query)`, and
+  `createErrorState(error, query)` create UI-ready state objects.
+- `createKnowledgeBaseSuggestionService(options)` creates a mock async service
+  around local fixtures for future UI work.
+
+## Input Shape
+
+```js
+{
+  query: "how do I reset my password",
+  threadId: "thread-support-001",
+  category: "account",
+  productArea: "login",
+  tags: ["password", "login"],
+  maxResults: 3
+}
+```
+
+## Output States
+
+The engine returns one of these state shapes:
+
+- `loading`: request has started, suggestions are empty, no error.
+- `success`: ranked suggestions are available.
+- `empty`: the request was valid, but no article passed the score threshold.
+- `error`: validation or service failure details are available.
+
+See `docs/contract.md` for full input, output, loading, empty, success, and error
+state details.
+
+## Fixtures
+
+`fixtures/knowledge-base-fixtures.json` contains:
+
+- Synthetic knowledge base articles.
+- Synthetic request contexts.
+- Expected top suggestions for deterministic tests.
+
+No fixture contains real users, production inbox content, credentials, wallet
+values, secrets, or live network references.
+
+## Known Limitations
+
+- Ranking is deterministic keyword scoring, not semantic search or an LLM.
+- The mock async service uses local memory only; it has no persistence layer.
+- No live network calls, search index, analytics event, or production data source
+  is introduced.
+- UI components and hooks are future issues.
+- Main app integration is intentionally out of scope.
 
-Do not wire this tool into the main app, routing, inbox architecture, wallet core, Stellar core, database schema, or existing design system unless a future integration issue explicitly allows it.
+## Acceptance Checklist
 
-See specs.md for the issue categories and contributor expectations.
+- [x] Core logic is implemented without linking into the main app.
+- [x] Inputs, outputs, loading states, and error states are documented.
+- [x] Deterministic local fixtures are included.
+- [x] No live network calls, secrets, or production data are introduced.
+- [x] Files changed by this issue are limited to this tool folder.

tools/v2/team/knowledge-base-suggestion/docs/contract.md

@@ -0,0 +1,155 @@
+# Knowledge Base Suggestion Contract
+
+This document describes the folder-local core engine for future UI and hook work.
+It is intentionally isolated from the main app.
+
+## Public API
+
+Import from `tools/v2/team/knowledge-base-suggestion/index.mjs`:
+
+```js
+import {
+  suggestKnowledgeBaseArticles,
+  createKnowledgeBaseSuggestionService,
+} from "./index.mjs";
+```
+
+## Request Input
+
+```js
+{
+  query: "Customer needs an invoice receipt",
+  threadId: "thread-billing-002",
+  category: "billing",
+  productArea: "billing",
+  tags: ["invoice"],
+  maxResults: 3
+}
+```
+
+Rules:
+
+- `query` is required and capped at 500 characters.
+- `threadId` is optional and must contain only letters, numbers, `_`, or `-`.
+- `category` is optional and must be one of the local allowlisted categories.
+- `productArea` is optional and sanitized as text.
+- `tags` are optional, capped, and sanitized.
+- `maxResults` is capped at 10.
+
+## Article Fixture Input
+
+Local article fixtures include:
+
+- `id`
+- `title`
+- `summary`
+- `body`
+- `category`
+- `status`
+- `url`
+- `productAreas`
+- `tags`
+- `keywords`
+- `relatedQuestions`
+- `updatedAt`
+
+Only `published` articles can be suggested. Draft and archived articles score as
+zero.
+
+## Output States
+
+### Loading
+
+```js
+{
+  status: "loading",
+  isLoading: true,
+  error: null,
+  query: "Customer needs an invoice receipt",
+  suggestions: [],
+  totalArticlesEvaluated: 0
+}
+```
+
+### Success
+
+```js
+{
+  status: "success",
+  isLoading: false,
+  error: null,
+  query: "Customer needs an invoice receipt",
+  suggestions: [
+    {
+      articleId: "kb-download-invoices",
+      title: "Download invoices and receipts",
+      summary: "Where billing admins can find invoices...",
+      category: "billing",
+      url: "/kb/billing/download-invoices",
+      score: 33,
+      confidence: "high",
+      matchedTerms: ["billing", "invoice", "receipt"],
+      reasons: ["Category match: billing."]
+    }
+  ],
+  totalArticlesEvaluated: 6
+}
+```
+
+### Empty
+
+```js
+{
+  status: "empty",
+  isLoading: false,
+  error: null,
+  query: "banana telescope garden question",
+  suggestions: [],
+  totalArticlesEvaluated: 6
+}
+```
+
+### Error
+
+```js
+{
+  status: "error",
+  isLoading: false,
+  error: {
+    message: "query is required",
+    field: "query"
+  },
+  query: "",
+  suggestions: [],
+  totalArticlesEvaluated: 0
+}
+```
+
+## Scoring Model
+
+The engine uses deterministic keyword scoring:
+
+- Category match: +6
+- Product area match: +5
+- Title token match: +5 each
+- Keyword match: +4 each
+- Tag match: +4 each
+- Related question match: +3 each
+- Summary match: +2 each
+- Body match: +1 each
+
+The same request and article list always produce the same order.
+
+## Loading and Error Behavior
+
+`createKnowledgeBaseSuggestionService()` wraps the pure suggestion engine in a
+mock async service for future UI testing. It can simulate latency or a failure
+without adding any network calls.
+
+## Known Limitations
+
+- This is not semantic search.
+- It does not call an LLM or external search index.
+- It does not read production inbox content.
+- It does not persist analytics or suggestion history.
+- It is not wired into any UI route yet.