AI Integration Strategy — Knowledge Hub

AI Integration Strategy — Knowledge Hub

Precedence note (S491, 22/07/2026): this master strategy doc predates the S491 tier-1 refresh. Where it conflicts with reference/platform-context.md, reference/platform-direction.md, or reference/deployment-architecture.md, the tier-1 docs win. The strategy/decision-log content here remains the canonical why record for the AI-integration layer set.

Date: 11 March 2026 (updated 7 April 2026, S151 Task 17b — restructure) Status: Active — master strategy document for all AI integration work Supersedes: .planning/.archive/.specs/spec4-ai-integration-architecture.md (6 March 2026, archived), .planning/.archive/.specs/2026-03-07-ai-integration-next-steps.md (7 March 2026, archived) Companion document: docs/reference/ai-integration-layers.md — technical layer map, capability crossover matrix, decision rules, and built/planned status. This document is the why; layers.md is the how. Author: Liam + Claude Code (Sessions 63, 64, 64b, 65, 66, 66b, 80, 81, 82, 108, 151)

---

Table of Contents

1. Vision and Strategic Positioning
2. Current State — What Is Built
3. Architecture — The Four-Layer Model
4. Layer 1: Remote MCP Server
5. Layer 2: MCP Apps
6. Layer 3: Cowork Plugin
7. Layer 4: Claude Code Plugin
8. AI Service Layer
9. Skill Files
10. Background Automation
11. Reorient Me — Phase 2 (AI Synthesis)
12. Library-to-Bid Feedback Loop
13. Presentation Split — Claude vs Web App
14. Enterprise Search Patterns — Reference Implementation
15. Client Context and Multi-Connector Experience
16. Onboarding and Setup
17. Implementation Sequence
18. Effort Estimates
19. Decision Log (10 active decisions)
20. Key Reference Documents

---

1. Vision and Strategic Positioning

1.1 Core Proposition

The knowledge base IS the product. Bids are the first application; the same structured data will power sales proposals, compliance, training, and other use cases. The navigation and information architecture must lead with the KB.

1.2 “Everyone Ends Up Working Within an LLM”

A strategic insight from the product owner (Session 62 brainstorm, §11.2 of State of the Product): most users already work within Claude Desktop, Claude.ai, Cowork, or similar LLM interfaces. Knowledge Hub’s job is to facilitate that — structuring data so AI can access it effectively, not competing for screen time.

This means:

• Claude is the primary AI interface — where most AI-powered interaction happens day-to-day. Users ask questions, get briefings, draft responses, and analyse coverage from within Claude
• The web app is the management layer — where users browse, edit, review, configure, and curate the golden-source knowledge base
• We don’t compete, we complement — Knowledge Hub’s value is in the data layer and API surface, not in building Claude’s equivalent inside the web app
• We adopt and customise, not reinvent — Anthropic and the ecosystem release plugins, skills, and commands regularly. We leverage existing patterns (enterprise-search, sales, operations) and customise for our domain

1.3 The SMB Differentiator

Knowledge Hub helps SMBs with AI readiness by providing easy interaction with company data. The key differentiator is creating golden-source knowledge bases that convert into actionable insights — not building another AI tool.

1.4 Design Principles (Reaffirmed)

• “Programmatic where possible” — save AI for tasks where natural language adds genuine value. Use deterministic functions for deterministic tasks
• “Observe and intervene” — not “prevent and approve”. Trust users by default, flag for review when quality dips
• “Invisible craft” — AI should be infrastructure, not a visible product feature
• “Claude for questions, web app for workflows” — reading and querying should work from anywhere; complex visual workflows live in the web app

For the full 13 governing UX principles (canonical product UX direction) see docs/reference/ux-principles.md.

---

2. Current State — What Is Built

2.1 AI Service Layer (Extracted — Session 65)

AI logic has been extracted from inline API route handlers into a shared service layer at lib/ai/. All AI integration points now call through this layer, which is also consumed by the MCP server. The integration points are:

#	Operation	Route/File	AI Provider
1	Classification	app/api/items/[id]/classify/route.ts	Claude Sonnet 4.6 (Pass 1 tool_use) + Claude Haiku 4.5 (Pass 2 entity validation)
2	Summarisation	app/api/summaries/generate/route.ts	Claude Sonnet 4.6 (tool_use)
3	Change report generation	app/api/change-reports/generate/route.ts	Claude Sonnet 4.6 (tool_use)
4	Embedding	app/api/embed/route.ts	OpenAI text-embedding-3-large (1024 dims)
5	Content extraction	app/api/extract/route.ts	Claude Sonnet 4.6
6	Vision/PDF analysis	app/api/items/[id]/vision/route.ts	Claude Sonnet 4.6 (vision)
7	Question extraction	app/api/bids/[id]/questions/extract/route.ts	Claude Sonnet 4.5 (structured outputs)
8	KB matching	app/api/bids/[id]/questions/match/route.ts	Claude Sonnet 4.5 (analysis) + OpenAI embeddings
9	Response drafting	app/api/bids/[id]/responses/draft*/route.ts	Claude Opus 4.6 (3-pass pipeline)
10	Quality check	lib/quality-check.ts	Claude Haiku 4.5 (structured outputs)
11	Tender metadata	lib/structured-outputs.ts	Claude Haiku 4.5

Model tier defaults are centralised in lib/anthropic.ts (MODEL_TIERS): analysis = claude-sonnet-4-5, drafting = claude-opus-4-6, quality = claude-haiku-4-5. The default service model for classification/summarisation is claude-sonnet-4-6 (overridable via AI_SUMMARY_MODEL). The Python ingestion pipeline pins to claude-opus-4-6 (scripts/kb_pipeline/config.py) for batch quality.

Service layer: lib/ai/index.ts (entry point), lib/ai/classify.ts, lib/ai/summarise.ts, lib/ai/change-reports.ts, lib/ai/embed.ts, lib/ai/extract.ts, lib/ai/vision.ts, lib/ai/questions.ts, lib/ai/matching.ts, lib/ai/drafting.ts, lib/ai/quality.ts, lib/ai/tender.ts, lib/ai/errors.ts (AIServiceError pattern).

Skill files: lib/ai/skills/ — 5 skill files (procurement-writing, uk-procurement, classification, classification-entity-types, governance) providing domain knowledge as structured prompts. Filename note: the procurement-writing skill was renamed S249 (ID-23) from bid-writing.md; the prose retains “bid” terminology as the UK procurement industry standard.

Supporting modules: lib/anthropic.ts (client, model tiers), lib/embeddings.ts (OpenAI), lib/bid-drafting.ts (3-pass pipeline), lib/citations.ts (Search Result Citations), lib/cost-estimation.ts, lib/bid-matching.ts, lib/ai-parse.ts (generic tool_use extractor), lib/validation/ai-schemas.ts (Zod schemas for AI responses).

Python pipeline: scripts/kb_pipeline/ (classify.py, summarise.py, embed.py) with its own Anthropic/OpenAI clients.

2.2 In-App AI Bridge

In-app AI interaction is handled by the ClaudePromptButton bridge, which generates contextual prompts and opens Claude directly. There is no embedded chat sidebar — see Decision 14 in §19 for the full rationale.

2.3 Reorient Me (Complete — Session 84)

• Interactive MCP App (Phase 3): Personal briefing app with 4-block layout (welcome, urgent, team, bids).
• GET /api/reorient endpoint with lib/reorient.ts data augmentation (display names via admin client, workspace/question IDs).
• Action model: sendMessage() for drafting workflows and callServerTool() for inline drill-downs.
• Registered via show_reorient_me tool and ui://reorient-me/app.html resource (see docs/generated/mcp-inventory.md for current indices).
• Full Phase 3 E2E verification complete. Live test counts in docs/generated/codebase-stats.md.

2.4 MCP Server (Complete — Sessions 65-108)

Architecture:

app/api/mcp/[transport]/route.ts    # Handler with withMcpAuth, WebStandardStreamableHTTPServerTransport
app/.well-known/oauth-protected-resource/route.ts  # RFC 9728
app/oauth/consent/page.tsx          # Warm Meridian consent UI
app/api/oauth/decision/route.ts     # Consent decision handler
lib/mcp/
  tools/                # Tool registrations across category files
  resources.ts          # Resources + prompts
  formatters.ts         # Markdown formatters per domain
  auth.ts               # Per-user Supabase client, role check, service fallback
  app-bundles.ts        # Generated HTML for MCP App resources (Vercel-safe)
  plugin-bundle.ts      # Generated ZIP for /api/plugin/download (Vercel-safe)

• Tool, resource, and prompt counts: see docs/generated/mcp-inventory.md (auto-generated). lib/mcp/CLAUDE.md carries the same numbers for the developer hot path.
• Auth: OAuth 2.0 with Supabase — per-user RLS, role-gated write tools.
• Transport: WebStandardStreamableHTTPServerTransport (SDK native) — fresh server + transport per request for Vercel serverless reliability.

2.5 What Does NOT Exist Yet

• Claude Code plugin (dedicated, beyond CLAUDE.md + checks)
• Python worker for processing_queue jobs
• Feedback loop AI enhancements (diff view, AI recommendations, answer variant routing)
• MCP Apps: Search Results, Review Queue, Content Timeline (Coverage Matrix, Bid Dashboard, Reorient Me, and Intelligence Feed are live)

2.6 Infrastructure Already in Place

• Freshness cron: recalculate-freshness-daily pg_cron at 03:00 UTC (deterministic, no AI)
• Background cron routes: 5 Vercel cron routes at app/api/cron/ — freshness-transitions, classification-quality, coverage-alerts, content-gaps, quality-score (all implemented S102-S107)
• Activity feed: get_grouped_activity_feed RPC with 3-CTE approach
• Bid response history: Auto-versioned via bid_response_history_snapshot trigger — already queried by Reorient Me
• Processing queue: processing_queue table exists for background jobs (no consumer yet)
• Content history: Auto-versioned immutable audit trail with created_by

---

3. Architecture — The Four-Layer Model

Knowledge Hub’s AI integration is organised into four layers on top of a shared data and service foundation. Layer 1 is the MCP server (raw data access); Layer 2 is MCP Apps (interactive visual cards rendered inside Claude); Layer 3 is the Cowork plugin (commands + skills that teach Claude how to use the tools); Layer 4 is the Claude Code plugin (developer-focused KB access).

The MCP server is the single reusable core. Layers 2-4 all build on it.

For the canonical layer map (ASCII diagram, per-layer descriptions, capability crossover matrix, and decision rules), see docs/reference/ai-integration-layers.md §1–§4.

---

4. Layer 1: Remote MCP Server

4.1 Approach

Remote MCP server built as a Next.js API route using the MCP SDK’s WebStandardStreamableHTTPServerTransport directly. Runs within the existing Vercel deployment with no new infrastructure. A fresh server + transport is created per request for Vercel serverless reliability (see Decision 13).

Route: app/api/mcp/[transport]/route.ts

Dependencies: @modelcontextprotocol/sdk, @modelcontextprotocol/ext-apps, zod

4.2 Tools, Resources, and Prompts

The MCP server exposes tools, resources, and prompts. For the canonical inventory — current counts, names, parameters, annotations, and category breakdown — see docs/generated/mcp-inventory.md (auto-generated from the codebase). Both lib/mcp/CLAUDE.md and docs/reference/ai-integration-layers.md also reference this single source of truth.

Tool description quality matters enormously. API-to-tool mapping creates suboptimal AI experiences. Tools must be described in terms of what the user gets, not what the API does. Markdown summaries in content for model consumption; rich structured data in structuredContent for MCP App rendering. This mirrors Notion’s approach of returning Markdown instead of hierarchical JSON for model consumption.

Tool annotations: Every tool ships with readOnlyHint, destructiveHint, idempotentHint, openWorldHint, and title annotations. The inventory file shows the full annotation breakdown.

Tool response format — content vs structuredContent: MCP tool responses support two output fields. content is text the model reads and reasons about (concise Markdown). structuredContent is data optimised for UI rendering (what MCP Apps display). Knowledge Hub tools return both.

Deferred tool loading: Investigation (S82) found that deferred tool loading is a client-side concern, not an MCP SDK feature. The current tool count is at the upper end of the recommended range (~30-40 tools) for accurate tool selection. If the count grows further, consider splitting into multiple MCP servers rather than deferred loading.

Evaluation tooling: Knowledge Hub runs three layers of MCP eval coverage (bun run test:mcp-eval, :rq, :fc) covering protocol compliance, response quality, and functional correctness against the live database.

4.5 Authentication

Recommended: OAuth 2.0 with Supabase.

Custom Connectors in Claude use OAuth for authentication. The flow:

1. User adds Knowledge Hub as a connector in Claude Settings > Connectors
2. Claude redirects to Knowledge Hub’s OAuth consent screen
3. User authenticates with Supabase credentials
4. OAuth provider issues a JWT; Claude stores it
5. All subsequent tool calls carry the token
6. MCP server validates via supabase.auth.getUser()

API key fallback: For initial development, a per-user API key stored in user_roles.metadata can be used with Bearer token auth. Transition to OAuth before client pilot.

4.6 Plan Availability

Claude Plan	Custom Connectors
Free	1 custom connector
Pro ($20/month)	Unlimited
Max ($100-200/month)	Unlimited
Team ($25-30/user/month)	Unlimited
Enterprise	Unlimited

Even free Claude users can connect to Knowledge Hub.

4.7 Claude Desktop Configuration

{
  "mcpServers": {
    "knowledge-hub": {
      "url": "https://knowledge-hub-seven-kappa.vercel.app/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer <user-token>"
      }
    }
  }
}

4.8 Anthropic API Integration

The Anthropic Messages API now supports MCP servers directly via the mcp_servers parameter (beta header: mcp-client-2025-11-20). This means any application using the Claude API can access Knowledge Hub tools without building MCP client infrastructure. Multiple servers can be connected in a single request.

4.9 User Interaction Patterns

Once connected, users interact naturally:

• “Search my knowledge base for ISO 27001 compliance content”
• “What bids are active and which ones are overdue?”
• “Show me the coverage gaps in Security”
• “Draft a response to this question using my KB: [question text]”
• “What has changed in Knowledge Hub since yesterday?”
• “Create a Q&A pair for our data retention policy”
• “Search KB for our case studies and create an Asana task to update the stale ones”

The last example demonstrates cross-connector orchestration — Claude routes to Knowledge Hub for the search and Asana for the task creation, with no integration between the two systems required.

---

5. Layer 2: MCP Apps

5.1 What Are MCP Apps?

MCP Apps are interactive HTML interfaces rendered inside MCP hosts (Claude Desktop, Claude.ai, VS Code, Cowork). They run in sandboxed iframes with bidirectional communication to the MCP server via postMessage.

Why MCP Apps matter for Knowledge Hub:

• Coverage matrices, bid progress dashboards, and review queues need visual density that text responses cannot provide
• Users get web-app-level interactivity without leaving Claude
• Apps can call MCP tools for live data and delegate actions to other connectors
• Aligns perfectly with “not competing for screen time” — the UI lives inside Claude’s conversation

5.2 MCP Apps Inventory

For the canonical built/planned list of MCP Apps (Coverage Matrix, Bid Dashboard, Reorient Me, Intelligence Feed, plus planned apps), see docs/reference/ai-integration-layers.md §5 (Layer 2 status table).

5.3 Technical Approach

Use the create-mcp-app skill for new apps and convert-web-app skill for adapting existing pages. Build purpose-built lightweight React components using @modelcontextprotocol/ext-apps/react with the useApp hook, rather than converting full Next.js pages.

The convert-web-app 6-step process:

1. Analyse the existing web app (data sources, dependencies, build system)
2. Investigate CSP requirements (every external origin must be declared)
3. Set up the MCP server (registerAppTool, registerAppResource)
4. Adapt the build pipeline (Vite with vite-plugin-singlefile)
5. Add MCP App initialisation alongside existing logic (hybrid pattern with isMcpApp detection — app works both standalone and inside Claude)
6. Add host styling integration (CSS variables with fallbacks)

Key constraints:

• Apps must be bundled as single HTML files (via vite-plugin-singlefile)
• External origins must be declared in CSP metadata
• No localStorage/sessionStorage (sandboxed iframe)
• Auth handled by the MCP server, not the app

Cross-connector delegation: MCP Apps can delegate actions to the host, which routes them to other connected MCP servers (subject to user consent). This means a Knowledge Hub MCP App could request “create an Asana task for this gap” — the host routes to Asana’s MCP server without Knowledge Hub needing direct Asana integration. The routing is: App → Host → Other MCP Server. The app never calls other servers directly.

5.4 Host Support

MCP Apps are supported by: Claude.ai, Claude Desktop, VS Code (Insiders), Goose, Postman, MCPJam, and ChatGPT.

---

6. Layer 3: Cowork Plugin

6.1 Structure

Based on patterns from the 7 installed Cowork plugins (enterprise-search, sales, operations, product-management, customer-support, design, productivity).

For the canonical command and skill list with what each does, see docs/reference/ai-integration-layers.md §1 (Layer 3 commands and skills tables) and §5 (Layer 3 status table).

6.2 The ~~knowledge base Connector Pattern

Cowork plugins use tool-agnostic ~~category references. Knowledge Hub maps to ~~knowledge base. This means the enterprise-search plugin (already installed by the client) will automatically include KB results when searching across sources — Claude routes ~~knowledge base queries to our MCP server.

6.3 Pattern Validation: Productivity Memory Management

The installed productivity Cowork plugin includes a memory-management skill with a two-tier memory architecture: CLAUDE.md as a “hot cache” (~30 people, ~30 terms, ~100 lines max) plus a memory/ directory for full storage (glossary, people, projects, context). Items promote/demote between tiers based on frequency — the “Hot 30” rule.

This validates Knowledge Hub’s existing approach: CLAUDE.md + MEMORY.md for session context, .planning/ + docs/ for deep reference. The pattern confirms that tiered context management (hot cache + cold storage) is the proven approach across Anthropic’s plugin ecosystem.

6.5 Skill Design Guidance

From the corpus of 34 Cowork skills analysed:

• Concise skills (30-50 lines): Decision frameworks with clear taxonomies. Use for: classification.md, content-governance.md
• Medium skills (100-200 lines): Multi-step workflows with templates. Use for: knowledge-synthesis.md, search-strategy.md
• Long skills (400-800+ lines): Complex creative tasks with quality systems. Use for: procurement-writing.md
• Always include: Trigger phrases in frontmatter, explicit anti-patterns, output format templates, confidence/quality indicators
• Cross-reference: Skills and commands should reference each other by name

6.6 Command Design

Commands follow a consistent pattern across all Cowork plugins:

• Numbered step workflow (typically 5-8 steps)
• Reference companion skills: “See the skill-name skill for…”
• Use $ARGUMENTS for user input
• Always include edge case handling as a final step
• “Standalone + supercharged”: work without connectors, better with them

6.7 Distribution

Cowork plugins can be distributed via:

• Private marketplace (enterprise admin configures via Customize menu)
• Direct install (copy plugin files)
• Per-user provisioning with auto-install to specific teams

---

7. Layer 4: Claude Code Plugin

7.1 Structure

For developer-focused KB access within Claude Code. The current state is the .claude/ directory with CLAUDE.md, quality checks, and a shared MCP connection. A dedicated plugin with KB-aware agents (kb-researcher, bid-assistant) is planned post-pilot. See docs/reference/ai-integration-layers.md §5 (Layer 4 status table) for the canonical built/planned breakdown.

7.2 Difference from Cowork Plugin

Aspect	Cowork Plugin	Claude Code Plugin
Audience	Knowledge workers (bid managers, content editors)	Developers working on KB
Commands	Domain-focused (/kb:briefing, /kb:coverage)	Dev-focused (/kb:search, /kb:change-report)
Agents	Not used in Cowork plugins	kb-researcher, bid-assistant
Hooks	Not used	Could trigger on file edits for KB sync
UI	Cowork conversation	Terminal output

7.3 Shared MCP Server

Both Cowork and Claude Code plugins point to the same MCP server URL. The MCP server is the single reusable core; plugins add domain-specific skills and workflows on top.

---

8. AI Service Layer

8.1 The Problem (Solved — S65)

All 12 AI integration points originally had logic inline in API route handlers. This was extracted in Sprint 3 (S65) into a shared service layer.

8.2 The Solution (Implemented)

AI logic was extracted from routes into lib/ai/ functions that all consumers call:

lib/ai/
├── index.ts              # Re-exports
├── classify.ts           # Classification (from classify route)
├── summarise.ts          # Summary generation (from summaries route)
├── match.ts              # KB matching (from bid matching route)
├── draft.ts              # Response drafting (from bid drafting route)
├── extract-questions.ts  # Question extraction (from tender extraction)
├── quality-check.ts      # Quality check (already partially extracted)
├── coverage-analysis.ts  # Gap detection (new)
├── skills/
│   ├── loader.ts                    # Reads and parses skill markdown files
│   ├── procurement-writing.md       # Bid writing best practices (renamed S249 ID-23)
│   ├── uk-procurement.md            # UK procurement regulations
│   ├── classification.md            # Classification guidance
│   ├── classification-entity-types.md # Entity-type classification taxonomy
│   └── governance.md                # Governance rules
└── prompts/
    ├── classify.ts       # Classification prompt templates
    ├── summarise.ts      # Summary prompt templates
    └── draft.ts          # Drafting prompt templates

8.3 Why This Was the Prerequisite

The AI service layer was the prerequisite for everything else:

• MCP tools call lib/ai/classify() instead of duplicating classification logic
• Background crons call lib/ai/ functions for batch operations
• Cowork/Claude Code skills reference the same domain knowledge from skill files

API routes are now thin wrappers that validate input, call lib/ai/ functions, and return responses.

8.4 Bid Query Deduplication

lib/dashboard.ts and lib/reorient.ts duplicate bid fetching logic. Extract shared bid query helpers as part of the service layer work.

---

9. Skill Files

9.1 Application-Level Skills (lib/ai/skills/)

These are markdown documents read at runtime by the application’s AI functions and injected into prompts as system context. They are NOT Claude Code skills/plugins — they are content files for the application’s own AI layer.

import { loadSkill } from './skills/loader';

const procurementWritingSkill = await loadSkill('procurement-writing');
const prompt = `${procurementWritingSkill}\n\n${basePrompt}`;

9.2 Cowork/Claude Code Skills

These are separate files in the Cowork plugin or Claude Code plugin structure. They teach Claude how to behave when working with Knowledge Hub data — query decomposition, bid writing patterns, content governance, classification guidance.

9.3 Relationship Between the Two

Application-level skills (in lib/ai/skills/) are injected into Claude API calls made by the server. Cowork/Claude Code skills (in the plugin) are instructions to Claude when working in the Claude interface. They share the same domain knowledge but serve different contexts:

Context	Skill Location	Consumer
Server-side AI (classification, drafting)	lib/ai/skills/	API routes, MCP tools
Claude conversation (Cowork, Desktop)	Plugin skills/	Claude directly

The content can be shared (copy procurement-writing guidance to both locations) but the format differs slightly (application skills are injected into prompts; Claude skills are SKILL.md with frontmatter triggers).

---

10. Background Automation

Full spec: docs/specs/background-automation-spec.md (4-eyes verified, S81).

Status: All 5 cron routes implemented (S102-S107).

10.1 Freshness Transition Notifications — Done

• Route: app/api/cron/freshness-transitions/route.ts
• Schedule: Daily
• Detects freshness state changes and notifies owners + admins

10.2 Classification Quality Monitor — Done

• Route: app/api/cron/classification-quality/route.ts
• Schedule: Weekly
• Reclassifies items with confidence below 0.7 or stale classifications (>90 days)
• Uses lib/ai/classify() — taxonomy-aware

10.3 Coverage Alerts — Done

• Route: app/api/cron/coverage-alerts/route.ts
• Schedule: Weekly
• Analyses template requirements vs KB content, detects gaps

10.4 Content Gap Detection — Done

• Route: app/api/cron/content-gaps/route.ts
• Schedule: Weekly
• Detects new/resolved/persistent gaps, sends notifications

10.5 Quality Score Recalculation — Done

• Route: app/api/cron/quality-score/route.ts
• Schedule: Daily
• Recalculates quality scores across the KB

All routes are protected by Vercel cron secret header and log runs in pipeline_runs table.

---

11. Reorient Me — Phase 2 (AI Synthesis)

11.1 Phase 1 Status — Complete

Phase 1 (deterministic rendering) is fully built. See §2.3. The spec at docs/specs/reorient-me-spec.md is implemented with all acceptance criteria met.

11.2 Phase 2 — MCP-First Delivery

Phase 2 (“AI synthesis”) is delivered via MCP across all surfaces simultaneously:

Delivery Path	How It Works
MCP tool	get_reorientation returns structured data → Claude synthesises naturally in conversation
MCP App	Interactive briefing card rendered inline in Claude (click to expand urgent items, view bid details)
MCP prompt	reorient prompt template provides the interaction pattern

11.3 Dependency Chain

Phase 1 (deterministic)           ✅ Done
  ↓
AI Service Layer (Sprint 3)       → Extract fetchReorientData to lib/ai/
  ↓
MCP Server (Sprint 4)             → get_reorientation tool
  ↓
Phase 2 delivered across:
  a) Claude conversation (MCP tool)
  b) Claude UI (MCP App — interactive briefing)

11.4 Pattern Validation: Sales Daily Briefing

The installed sales Cowork plugin includes a daily-briefing skill that is a direct analogue to Reorient Me — same concept of “here’s what matters today.” Its patterns validate our approach and provide implementation reference:

• Connector data aggregation (calendar, CRM, email, enrichment sources)
• 6-level priority ranking system
• Quick mode vs End of Day mode variants
• Follow-up question suggestions

The Reorient Me MCP tool should follow this same pattern, returning structured data that Claude synthesises into a natural briefing.

11.5 Spec Status

reorient-me-spec.md (now archived to .planning/.archive/.specs/) — Phase 1 complete. Phase 2 is delivered via MCP across all surfaces (tool, app, prompt) as described above.

---

12. Library-to-Bid Feedback Loop

12.1 Current State

Forward path (built): KB feeds bids. Tender upload → question extraction → KB matching → AI drafting → quality check.

Reverse path (partially built): Bid outcome dialog with “integrate to KB” checkbox → KBIntegrationReview dialog → create/update content items.

12.2 What’s Missing

1. No quality comparison — no diff view when updating existing content
2. No AI analysis — no comparison of winning response vs existing Q&A pair
3. No automatic detection — only triggered by explicit checkbox
4. No answer variant handling — doesn’t route to standard vs advanced answer
5. No win signal propagation — winning content not boosted in search ranking
6. No batch workflow — reviewing 20+ responses individually is tedious

12.3 Recommended Phases

| Phase | What | Effort | | ------- | ----------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Phase 1 | Diff view for updates (side-by-side comparison) | 0.5 sessions | | Phase 2 | AI-assisted recommendations (Claude analyses response vs source) | 1 session | | Phase 3 | Answer variant routing (standard/advanced selector) | 0.5 sessions | | Phase 4 | Win signal propagation (search ranking boost for winning content) | 1 session | Done (S80) — hybrid_search and search_for_bid_response RPCs both multiply similarity by (1 + 0.03 * win_rate). Diff view, AI recommendations, and answer variant routing (Phases 1-3) remain unbuilt |

12.4 MCP Integration

The feedback loop can be triggered from Claude: “Review the winning responses from the IT Support bid and suggest which ones should update the KB.” This would use MCP tools to fetch bid responses, compare against existing content, and present recommendations — all within Claude’s conversation.

---

13. Presentation Split — Claude vs Web App

13.1 What Lives in Claude (MCP/Plugin)

Capability	Why Claude
Search across KB	Users already work in Claude; no app switching
Cross-connector queries	”Search KB AND create Asana task” only works in Claude
Bid briefings	Natural language synthesis adds genuine value
Coverage gap analysis	AI interprets data and explains gaps
Draft responses	Claude uses KB + context to generate responses
Content classification	Trigger reclassification from Claude workflow
Reorientation	”What changed since yesterday?” is a natural prompt
Prompts	Reusable templates for common KB workflows
Skills	Domain knowledge that makes Claude smarter about the user’s context

13.2 What Lives in the Web App

Capability	Why Web App
Browse and filter content	Spatial navigation, grid/list, pagination
Inline editing	Rich text, version history, metadata
Review workflow	Speed triage cards, approve/reject — visual UI
Dashboard and analytics	Charts, coverage matrices — visual data density
Bid session editor	Side-by-side question/response with streaming
File upload and ingestion	Drag-and-drop, progress, batch operations
User and role management	Settings, invitations, permissions
Taxonomy management	Drag-and-drop reordering, CRUD
ClaudePromptButton bridge	Contextual prompt generation, opens Claude directly
Notifications and governance	Visual indicators, badges, review queues

13.3 The Overlap Principle

Both surfaces should support search and briefings. Users should never feel they must switch to accomplish something. The MCP server and the web app share the same backend logic — both call lib/ai/ functions. The ClaudePromptButton bridge provides in-app entry points to Claude-based workflows.

13.4 MCP Apps Bridge the Gap

MCP Apps blur the line in a positive way — users get web-app-level visual density (coverage matrix, bid dashboard, search results) without leaving Claude. This is the “not competing” principle in action: the visual UI lives inside Claude’s conversation rather than in a separate tab.

13.5 The Anti-Pattern to Avoid

The “chatbot in a sidebar” trap: a generic in-app chat surface disconnected from context. Knowledge Hub deliberately does not embed one — it would duplicate what Claude Desktop, Claude.ai, and Cowork already provide, while adding third-party dependency risk and pulling against the “AI is invisible infrastructure” principle. The primary AI value is delivered through:

1. Reorient Me section (deterministic, no chatbot needed)
2. Inline AI actions (classify, summarise) triggered by buttons, not chat
3. Smart defaults (auto-classification on ingest)
4. ClaudePromptButton bridge for contextual AI entry points

---

14. Enterprise Search Patterns — Reference Implementation

14.1 What to Adopt

The enterprise-search plugin (3 skills, 2 commands) provides mature patterns:

Query type classification (from search-strategy skill): Decision, Status, Document, Person, Factual, Temporal, Exploratory — each gets different search strategy and relevance scoring weights. Maps directly to how we should tune our hybrid search.

Confidence model (from knowledge-synthesis skill): freshness × authority × agreement. Maps to our existing freshness system.

Deduplication and synthesis (from knowledge-synthesis skill): Cross-source deduplication, conflicting information handling, summarisation strategies by result set size. Anti-patterns: never list by source, never bury the answer, never present uncertain info with high confidence.

Source prioritisation (from source-management skill): Different priorities for different query types. For Knowledge Hub: Q&A pairs > policies > case studies > articles for factual queries; freshness weighting for status queries.

14.2 What to Customise

• Query decomposition: KB is a single source, but content TYPE decomposition (search Q&A pairs separately from articles) improves results
• Authority hierarchy: replace source-type hierarchy with content-type hierarchy (Q&A pairs > policies > case studies > blogs)
• Confidence levels: map to our freshness system (fresh = high confidence, stale = flag as potentially outdated)

14.3 The ~~knowledge base Integration

With Knowledge Hub’s MCP server connected as a connector, the enterprise-search plugin will automatically route ~~knowledge base queries to our tools. This means the client gets unified cross-source search (KB + Notion + Asana + HubSpot) with zero additional integration work.

---

15. Client Context and Multi-Connector Experience

15.1 First Client’s Stack

The first client uses: Notion, Clay, Asana, HubSpot, and (soon) Knowledge Hub. Knowledge Hub becomes the 5th connector. The user’s mental model is already established: each connector is a data source, Claude orchestrates across them.

15.2 Cross-Connector Workflows

Claude handles multi-connector workflows natively:

“Search my KB for ISO 27001 content, summarise what we have, and create an Asana task to review the stale items”

Claude routes to Knowledge Hub for the search, synthesises the results, then routes to Asana for task creation. No integration between KB and Asana required — Claude is the orchestrator.

16.3 Tool Description Differentiation

Knowledge Hub’s tools must have clear, distinct descriptions so Claude can disambiguate them from Notion (which also holds documents) and HubSpot (which also has company data). The key differentiator: Knowledge Hub is the golden-source knowledge base — structured, classified, freshness-tracked content with AI-powered search. Notion is for working documents; KB is for authoritative, curated knowledge.

16.4 Scheduled Tasks and Automation

Cowork supports scheduled tasks. The client could schedule:

• Daily KB briefing at 9am (“What changed in my KB overnight?”)
• Weekly coverage gap report on Mondays
• Bid deadline reminders

Claude Code supports /loop for recurring tasks in development sessions.

---

16. Onboarding and Setup

16.1 Claude.ai / Claude Desktop (Custom Connector)

1. User navigates to Claude Settings > Connectors
2. Clicks “Add connector” and enters KB MCP server URL
3. Claude redirects to Knowledge Hub’s OAuth consent screen
4. User authenticates with KB credentials (Supabase Auth)
5. Connector appears in the user’s connector list with toggle
6. In any conversation, user enables the connector via + > Connectors

16.2 Cowork (Plugin Install)

1. Knowledge Hub plugin distributed via private marketplace
2. User installs from Customize menu
3. Plugin auto-configures MCP connector, prompting for OAuth on first use
4. Skills, commands, and connector become available immediately

16.3 Web App Settings Page

The Settings page should include a “Connect to Claude” section:

1. Guide explaining what connecting to Claude enables
2. One-click copy of the MCP server URL
3. OAuth setup or API key generation
4. “Test connection” button
5. Quick-start prompts to verify the connection

16.4 First-Use Experience

When a user first enables the connector, Claude sees the tool definitions and can describe available capabilities if asked (“What can you do with my Knowledge Hub?”). Claude will proactively use KB tools when queries match — no special onboarding needed inside Claude.

For client-facing onboarding documentation see docs/client-documentation/Knowledge Hub — Claude Integration Guide.md.

---

17. Implementation Sequence (Outstanding)

Sprint 8: Background Automation — Complete (S102-S107)

All 5 cron routes implemented. See section 10 for details.

Future (After Client Pilot)

Item	Notes
Template-driven completeness Phases 2-6	MCP tools, web UI, gap loop, templates, onboarding. Phase 1 data ready (66 requirements)
Claude Code plugin	Developer-focused KB access
MCP App: Reorient Me	Interactive briefing card inside Claude (see §11) — Built (S84)
MCP App: search results viewer	Rich result cards with domain/type filters
MCP App: review queue	Speed-triage cards in Claude
MCP settings UI + connection test	Settings page for MCP connection
Feedback loop Phases 1-3	Diff view, AI recommendations, answer variant routing

---

18. Effort Estimates

Sprint	Scope	Sessions	Actual
Sprint 3	AI service layer extraction + skill files	1-2	1 (S65)
Sprint 4	MCP server (5 core tools + auth + settings)	1-2	1 (S65, combined with Sprint 3)
Sprint 5	MCP server (full) + OAuth + serverless fix	2-3	2 (S66 + S66b)
Sprint 6	Data quality + entity graph + curation	2-3	2 (S67 + S68)
Sprint 7a	Additional MCP tools + plugin	1-2	1 (S69)
Sprint 7b	MCP App: Coverage Matrix	1-2	1 (S72)
Sprint 7c	MCP App: Bid Dashboard + polish	1-2	1 (S76)
Sprint 7d	Bid Dashboard drill-down	1	1 (S81)
Sprint 8	Background automation	1-2	Done (S102-S107)
Total to MVP	Sprints 3-5 (MCP server live with OAuth)	4-7	4 sessions
Total comprehensive	All sprints including polish	10-15	Complete

---

19. Decision Log

#	Decision	Rationale	Revisit Trigger
1	Claude-first, web-app-second	Users work within Claude; KB structures data for AI access	User feedback prefers web app AI
2	MCP server prioritised over in-app chat	MCP reaches more surfaces (Claude.ai, Desktop, Cowork, Code, API)	Resolved (S109) — see Decision 14
3	OAuth 2.0 for MCP auth	Custom Connectors use OAuth; implemented in S66 with Supabase JWT validation, RFC 9728 metadata, consent UI	N/A — implemented
4	Adopt Enterprise Search patterns	Proven at scale, aligned with ~~knowledge base category	Patterns don’t fit KB’s needs
5	Purpose-built MCP Apps (not converted pages)	Next.js pages too complex for single-HTML bundling	convert-web-app approach viable
6	Cowork plugin over Claude Code plugin first	Client is knowledge workers, not developers	Dev workflow demand high
7	Deterministic reorient-me first, AI synthesis via MCP	Programmatic where possible; MCP unlocks synthesis on all surfaces	Phase 1 feels insufficient
8	Skill files dual-location	lib/ai/skills/ for server-side prompts; plugin skills/ for Claude	Maintenance burden too high
9	WebStandardStreamableHTTPServerTransport over mcp-handler	mcp-handler’s shared transport corrupts on warm Vercel instances; SDK’s web standard transport with fresh server + transport per request is reliable (S66b)	mcp-handler shared-state issue fixed upstream
10	In-app chat sidebar removed (S109)	Investigation (S108) showed an embedded chat sidebar duplicated MCP capabilities, added third-party dependency risk, and conflicted with “AI is invisible infrastructure”. ClaudePromptButton bridge preserved.	N/A — completed

---

20. Key Reference Documents

Document	Purpose
docs/reference/ai-integration-layers.md	Technical layer map, crossover matrix, decision rules
docs/generated/mcp-inventory.md	Auto-generated tool/resource/prompt inventory (canonical counts)
lib/mcp/CLAUDE.md	Developer conventions for the MCP module
docs/reference/state-of-the-product.md §11	Product direction and brainstorm outcomes
docs/reference/ai-visibility-policy.md	AI framing rules and visibility decisions
docs/reference/ux-principles.md	The 13 governing UX principles (extracted from ADS v1.0)
.planning/.archive/.specs/reorient-me-spec.md	Reorient Me implementation spec (archived; Phase 1 done)
.planning/.archive/.specs/background-automation-spec.md	Background automation spec (archived; all 5 cron routes built)
.planning/.archive/.specs/bid-dashboard-enhancements-spec.md	Bid Dashboard drill-down spec (archived; implemented S81)
docs/specs/template-driven-completeness-spec.md	Template-driven KB completeness (6 phases)
.planning/.archive/.specs/copilotkit-investigation-s108.md	Historical investigation that informed Decision 10 (archived)
.planning/research/claude-capabilities/mcp-apps-overview.md	MCP Apps specification and patterns
.planning/research/claude-capabilities/plugins/enterprise-search/	Enterprise Search reference plugin
.planning/research/claude-capabilities/	40+ Claude capability research documents
.claude/plugins/	7 installed Cowork plugins (patterns reference)
.claude/skills/mcp-builder/	MCP server building skill with best practices
.claude/skills/create-mcp-app/	MCP App creation skill
.claude/skills/convert-web-app/	Web app to MCP App conversion skill
claude-desktop-feedback-on-mcp-tools.md	Claude Desktop feedback on MCP tools — 7 improvement opportunities
CLAUDE.md	Project conventions, architecture, gotchas

Retired Documents

Document	Status
.planning/.archive/.specs/spec4-ai-integration-architecture.md	Superseded by this document (archived). Valid content (AI service layer, skill files, background automation) absorbed
.planning/.archive/.specs/2026-03-07-ai-integration-next-steps.md	Superseded by this document (archived). Research and analysis absorbed and updated
.planning/.archive/.reference/ads-v1.md	ADS v1.0 (10 February 2026) — archived 7 April 2026 (S151 Task 17b). UX principles extracted to docs/reference/ux-principles.md; AI framing extracted to docs/reference/ai-visibility-policy.md

---

AI Integration Strategy produced: 8 March 2026, updated 24 March 2026 (S110 — in-app chat references removed, renumbered to 4-layer model), updated 7 April 2026 (S151 Task 17b — restructure: counts referenced from inventory, duplicated layer map removed in favour of cross-link to layers.md, decision log compacted to 10 active entries, §16 numbering fixed). Sessions: 63 (research), 64 (Sprints 1-2), 64b (bug fixes, strategy consolidation), 65 (Sprints 3-4: AI service layer + MCP server core), 66 (Sprint 5: MCP OAuth + core tools), 66b (serverless crash fix), 67-68 (Sprint 6: data quality + entity graph), 69 (Sprint 7a: additional tools + plugin), 72 (Sprint 7b: Coverage Matrix app), 76 (Sprint 7c: Bid Dashboard app), 80 (taxonomy, win signal), 81 (Sprint 7d: drill-down, background automation spec), 82 (docs refresh), 84 (Sprint 9: Reorient Me Phase 3), 102-107 (Sprint 8: background automation, quality tools, content lifecycle), 151 (audit + restructure).