AI Integration Layers — Reference Guide
AI Integration Layers — Reference Guide
Section titled “AI Integration Layers — Reference Guide”Last updated: 7 April 2026 (S151 Task 17b — restructure) Status: Active
reference document Companion document:
docs/reference/ai-integration-strategy.md — vision, decision log, sprint
history, effort estimates, presentation-split philosophy. This document is the
technical layer map (the how); strategy.md is the vision and decision
log (the why). Counts and tool inventories live in
docs/generated/mcp-inventory.md (auto-generated truth source).
Contents
Section titled “Contents”- The Four Layers — What Each Does
- How They Connect
- Crossover Analysis — What Goes Where
- Decision Rules for Future Development
- What’s Built vs Planned
- Documentation Hierarchy
1. The Four Layers — What Each Does
Section titled “1. The Four Layers — What Each Does”Knowledge Hub’s AI integration is organised into four layers. Each serves a different audience in a different context, but they all draw from the same underlying data and logic.
┌─────────────────────────────────────────────────────────────┐│ Knowledge Hub Data Layer ││ Supabase (pgvector, RLS, content, bids, taxonomy, entities)││ + AI Service Layer (lib/ai/ — shared logic for all layers) ││ + Skill Files (lib/ai/skills/ — domain knowledge) │└─────────────┬───────────────────────────────┬───────────────┘ │ │ ┌──────────▼──────────┐ ┌──────────▼──────────┐ │ Next.js API Routes │ │ MCP Server │ │ │ │ (Vercel-hosted) │ └──────────────────────┘ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Layer 1: MCP Tools │ │ │ │ Layer 2: MCP Apps │ │ │ │ Layer 3: Plugin │ │ (commands + skills) │ │ │ │ Layer 4: Claude Code │ │ (dev workflow) │ └──────────────────────┘Layer 1: MCP Server — The Data Access Layer
Section titled “Layer 1: MCP Server — The Data Access Layer”What it is: A set of tools, resources, and prompts that give any MCP client direct access to Knowledge Hub data. This is the raw plumbing — search content, fetch bids, check freshness, create items, classify content, trigger MCP Apps, and more.
Inventory (counts, names, parameters, annotations): see
docs/generated/mcp-inventory.md (auto-generated; the canonical source of
truth). lib/mcp/CLAUDE.md carries the same totals for the developer hot path.
Who uses it: Claude Desktop, Claude.ai, Cowork, Claude Code, any MCP- compatible client. When you add Knowledge Hub as a connector in Claude, Layer 1 is what Claude gets access to.
Key point: The MCP server is the single reusable core. Every other layer builds on top of it (Layers 2-4).
What it does NOT do: It does not tell Claude how to use the tools well. It provides raw capabilities — searching, fetching, classifying — but it does not include guidance on query decomposition, bid writing conventions, or confidence assessment. That is what Layers 2 and 3 add.
Layer 2: MCP Apps — Visual Interfaces Inside Claude
Section titled “Layer 2: MCP Apps — Visual Interfaces Inside Claude”What it is: Interactive HTML interfaces rendered inside Claude’s conversation as embedded cards. Think of them as mini web pages that appear inline when Claude needs to show you something visual — a coverage heatmap, a bid progress dashboard, a search results viewer.
Who uses it: The same people using Claude Desktop, Claude.ai, or Cowork. The apps appear automatically when Claude determines a visual display would be more useful than a text response.
Why it matters: Some information is much better shown than told. A coverage matrix with colour-coded cells is instantly readable; the same data as text is a wall of numbers. MCP Apps bridge the gap between Claude’s text responses and the web app’s visual richness — without making the user switch tabs.
Key point: MCP Apps get their data by calling Layer 1 (MCP tools). They do not have their own data access — they are a presentation layer on top of the tools.
Status: Built. Four MCP Apps live (see docs/generated/mcp-inventory.md
resources #9–#12):
- Coverage Matrix — Domains x freshness grid, drill-down, heat map, gap cards (S72)
- Bid Dashboard — Bid cards, urgency sorting, progress bars, drill-down to sections/questions with KB search and confidence badges (S76, S81)
- Reorient Me — Interactive personal briefing with 4-block layout (S84)
- Intelligence Feed — Sector intelligence change-report cards scoped to a workspace/period
All are Vite single-file builds, inlined as string constants in
lib/mcp/app-bundles.ts for Vercel deployment. Triggered via the corresponding
show_* MCP tools (apps category) or ui:// resources.
Layer 3: Knowledge Hub Plugin — Commands and Skills
Section titled “Layer 3: Knowledge Hub Plugin — Commands and Skills”What it is: A Cowork/Claude Code plugin that provides slash commands
(/kb:search, /kb:briefing, /kb:draft-response, etc.) and skills
(procurement-writing, search-strategy, knowledge-synthesis, content-governance,
classification). This is the “intelligence layer” — it teaches Claude how to use
the MCP tools effectively for knowledge management and bid writing.
Who uses it: Knowledge workers (bid managers, content editors) in Cowork or Claude.ai. Also works in Claude Code, though the audience there is mainly developers.
The critical difference from Layer 1: Layer 1 gives Claude the ability to search. Layer 3 gives Claude the expertise to search well. For example:
- Layer 1 alone: Claude calls
search_knowledge_basewith the user’s query verbatim. Returns raw results. - Layer 3 added: Claude decomposes the query using the search-strategy skill, determines whether to search the general KB or Q&A library or both, applies domain filtering, evaluates result quality using the knowledge- synthesis skill, and synthesises a coherent answer with citations and confidence assessment.
Commands (6):
| Command | What it does | Skills it uses |
|---|---|---|
/kb:search | Search the KB with query decomposition and synthesis | search-strategy, knowledge-synthesis |
/kb:briefing | Get a reorientation briefing | — |
/kb:bid-status | Overview of active bids | — |
/kb:coverage | Analyse coverage gaps | content-governance |
/kb:draft-response | Draft a bid response with citations | procurement-writing, search-strategy, knowledge-synthesis |
/kb:change-report | Generate a KB change report | content-governance |
Skills (5):
| Skill | What it teaches Claude |
|---|---|
| search-strategy | Query decomposition, search type selection, domain filtering, similarity score interpretation |
| procurement-writing | UK public procurement conventions, response structure, confidence postures, word limit management |
| knowledge-synthesis | How to combine multiple KB sources, handle contradictions, format citations, assess confidence |
| content-governance | Freshness lifecycle, quality flags, governance review workflows |
| classification | Domain taxonomy guidance, content type rules, when to reclassify |
Standalone vs Supercharged: Every command works in two modes. Without the MCP connector, you paste content and Claude applies the skills manually. With the connector, Claude searches the live KB directly — same skills, live data.
Layer 4: Claude Code Plugin — Development Workflow
Section titled “Layer 4: Claude Code Plugin — Development Workflow”What it is: Development-focused tools and context for Claude Code sessions
working on the Knowledge Hub codebase. This is the .claude/ directory
structure — CLAUDE.md, quality checks, and the Cowork plugin itself (which lives
at .claude/plugins/knowledge-hub/).
Who uses it: Developers (currently Liam + Claude Code) working on the codebase.
How it differs from Layer 3: Layer 3 is for using Knowledge Hub (searching, drafting, reviewing). Layer 4 is for building Knowledge Hub (coding, testing, deploying). They share the same MCP server connection but serve completely different purposes.
What exists:
- CLAUDE.md with project conventions, architecture, and gotchas
- 10 quality check files in
.claude/checks/(accessibility, architecture, design system, error handling, etc.) - Project memory (MEMORY.md) for cross-session context
Status: Partially built. The quality checks and project context exist. A dedicated Claude Code plugin with KB-aware agents (kb-researcher, bid-assistant) is planned for after the client pilot.
2. How They Connect
Section titled “2. How They Connect”Plugin Commands CALL MCP Tools
Section titled “Plugin Commands CALL MCP Tools”When you run /kb:search what is our ISO 27001 approach? in Cowork, here is
what happens:
- The search command (Layer 3) parses your query
- The search-strategy skill (Layer 3) classifies the query type and determines the optimal search approach
- The command calls
search_knowledge_baseand/orsearch_qa_library(Layer 1 MCP tools) to get results - The knowledge-synthesis skill (Layer 3) evaluates result quality, deduplicates, and synthesises
- Claude presents a coherent answer with citations
The command adds expertise; the MCP tool does the data retrieval. Without the command, Claude could still call the tool — but it would not apply the same structured approach.
MCP Apps RENDER Data from MCP Tools
Section titled “MCP Apps RENDER Data from MCP Tools”When Claude decides to show you a coverage matrix, here is what happens:
- The coverage matrix MCP App (Layer 2) loads inside Claude’s conversation
- The app calls
get_dashboard_summary,get_quality_summary, andget_freshness_report(Layer 1 MCP tools) to get data - The app renders the data as an interactive visual — colour-coded cells, click-to-drill-down, hover for details
- You interact with the app directly inside Claude’s conversation
The app is a presentation layer; it has no data access of its own.
Skills TEACH Claude How to Use the Tools
Section titled “Skills TEACH Claude How to Use the Tools”Skills are not code — they are structured guidance documents. They do not call tools themselves. Instead, they teach Claude:
- When to use each tool (search-strategy teaches when to use
search_qa_libraryvssearch_knowledge_base) - How to interpret results (knowledge-synthesis teaches similarity score thresholds and freshness assessment)
- What conventions to follow (procurement-writing teaches UK procurement formatting and response structure)
Commands reference skills using @skill-name syntax. Claude reads the skill
content and applies it to its tool usage.
The AI Service Layer Is the Foundation
Section titled “The AI Service Layer Is the Foundation”All four layers ultimately draw from:
lib/ai/— AI integration points (classify, summarise, draft, embed, extract, match, quality check, etc.)lib/ai/skills/— server-side skill files injected into AI prompts (procurement-writing, uk-procurement, classification, governance)- Supabase — database with RLS, pgvector search, and the full table set (see
docs/reference/SCHEMA-QUICK-REFERENCE.mdfor the canonical schema)
This shared foundation means that improvements to the AI logic benefit all layers simultaneously.
3. Crossover Analysis — What Goes Where
Section titled “3. Crossover Analysis — What Goes Where”This table maps every capability to the layer(s) where it lives or will live. This is the key reference for understanding which pieces exist and how they relate.
| Capability | MCP Tool (Layer 1) | Plugin Command (Layer 3) | Plugin Skill (Layer 3) | MCP App (Layer 2) | Notes |
|---|---|---|---|---|---|
| Search KB | search_knowledge_base | /kb:search | search-strategy, knowledge-synthesis | Search Results App (planned) | The plugin command adds query decomposition and synthesis via skills. The app would show rich result cards with filters. |
| Search Q&A library | search_qa_library | (used within /kb:search and /kb:draft-response) | search-strategy | — | Called by commands when queries target Q&A content specifically. |
| Coverage analysis | get_dashboard_summary + get_quality_summary + get_freshness_report + get_coverage_gaps | /kb:coverage | content-governance | Coverage Matrix App (built) | Interactive domain heatmap with drill-down and gap cards. The command produces text analysis. |
| Bid status | list_active_bids + get_bid_detail | /kb:bid-status | — | Bid Dashboard App (built) | Visual progress bars, deadline countdowns, urgency sorting, drill-down to sections/questions/KB search. |
| Bid question detail | get_bid_question | (used within /kb:bid-status) | — | Bid Dashboard App (drill-down) | Question-level detail with KB content search and confidence badges. |
| Draft bid response | search_knowledge_base + search_qa_library | /kb:draft-response | procurement-writing, search-strategy, knowledge-synthesis | — | Skills are the key value-add here. Without them, Claude drafts generically; with them, it follows UK procurement conventions and assesses confidence. |
| Reorientation briefing | get_reorientation + show_reorient_me | /kb:briefing | — | Reorient Me App (built) | Interactive personal briefing card inside Claude. |
| Content digest | get_dashboard_summary + get_freshness_report | /kb:change-report | content-governance | — | The command categorises and prioritises changes. |
| Classify content | classify_content | — | classification | — | The skill teaches when and how to classify. No dedicated command yet. |
| Generate summary | generate_summary | — | — | — | Standalone tool, no command wrapper needed. |
| Create content | create_content_item | — | — | — | Available via tool; no command wrapper yet. |
| Get content item | get_content_item | (used within commands) | — | — | Supporting tool used by commands and apps. |
| Entity graph | get_entity_relationships | — | — | — | Query relationships between entities across content. |
| Content citations | cite_content + get_content_effectiveness | — | — | — | Feedback loop — tracks which content gets used in bids and whether those bids win. |
| Edit content | update_content_item | — | — | — | Built (Session 69). Edit existing content via MCP — title, metadata, tags. The content (body) field is retired for source_document owners since id-392 — the body lives in content_chunks/reference_items and is read-only via the composed-body helper; Q&A pairs keep answer_standard/answer_advanced. |
| Quality audit | audit_content | — | — | Review Queue App (planned) | Built (Session 69). Returns items matching quality filters (thin content, low confidence, missing fields). |
| Find duplicates | find_similar_items | — | — | — | Built (Session 69). Uses embeddings to find similar items above a cosine threshold. |
| Batch fetch | get_content_items | — | — | — | Built (Session 69). Fetch multiple items by ID array. |
4. Decision Rules for Future Development
Section titled “4. Decision Rules for Future Development”When adding a new capability, use these rules to decide which layer(s) it belongs in.
Is it a raw data operation?
Section titled “Is it a raw data operation?”Put it in Layer 1 (MCP Tool).
If the capability is about reading, writing, or querying data — and does not require domain expertise or visual presentation — it is a tool. Tools are the building blocks that everything else uses.
Examples: search_knowledge_base, get_content_item, create_content_item,
update_content_item.
Does it need domain expertise or multi-step orchestration?
Section titled “Does it need domain expertise or multi-step orchestration?”Add a Plugin Command + Skill (Layer 3).
If the capability requires Claude to follow a specific workflow, apply domain knowledge, or orchestrate multiple tools in a particular sequence, wrap it in a command backed by skills. Commands are thin wrappers that reference skills and call tools.
Examples: /kb:draft-response (calls two search tools, applies three skills,
follows a 7-step workflow), /kb:coverage (calls three tools, applies
governance skill).
Does it need visual density?
Section titled “Does it need visual density?”Build an MCP App (Layer 2).
If the data is better shown than told — tables with colour coding, progress bars, interactive charts, click-to-drill-down — build an MCP App. Apps render inside Claude’s conversation as embedded cards.
Examples: Coverage matrix (domain heatmap), bid dashboard (progress bars and deadlines), search results (rich cards with filters).
Is it a development workflow?
Section titled “Is it a development workflow?”Put it in Layer 4 (Claude Code plugin) only.
If the capability is about coding, testing, deploying, or maintaining the Knowledge Hub codebase, it belongs in the development layer. This includes quality checks, architecture conventions, and project context.
Examples: Quality checks in .claude/checks/, CLAUDE.md conventions,
MEMORY.md session context.
Does it need to work in the web app?
Section titled “Does it need to work in the web app?”Use API routes + ClaudePromptButton bridge.
If the capability must be available within the Knowledge Hub web application itself — not inside Claude — use standard API routes for deterministic operations and the ClaudePromptButton bridge for AI-assisted interactions (generates contextual prompts and opens Claude directly).
Examples: Inline classification buttons, the Reorient Me section on the homepage, Claude prompt buttons on browse and item detail pages.
Can it live in multiple layers?
Section titled “Can it live in multiple layers?”Yes — but each layer should add distinct value.
Search is a good example: it exists as a tool (raw search), a command (orchestrated search with synthesis), and will exist as an app (visual result cards). Each layer adds something the others cannot provide. Do not duplicate for the sake of coverage — duplicate only when the layer adds genuine value.
The Skill Question
Section titled “The Skill Question”When deciding whether something needs a skill, ask: “Would Claude do a noticeably worse job without specific guidance?” If yes, write a skill. If Claude’s general knowledge is sufficient, do not add a skill.
5. What’s Built vs Planned
Section titled “5. What’s Built vs Planned”Layer 1: MCP Server
Section titled “Layer 1: MCP Server”For current tool, resource, and prompt counts, see
docs/generated/mcp-inventory.md (auto-generated).
| Component | Status | Notes |
|---|---|---|
| Tools | Built (Sessions 65-108) | Full OAuth 2.0, per-user RLS. See inventory for current count |
| Resources | Built (Sessions 66-108) | URI templates with list support, plus ui:// resources for MCP Apps |
| Prompts | Built (Session 66) | Reorient, bid briefing, coverage, draft, review |
| OAuth 2.0 authentication | Built (Session 66) | Supabase JWT, RFC 9728 metadata, consent UI |
| Serverless transport | Built (Session 66b) | WebStandardStreamableHTTPServerTransport (SDK native) |
update_content_item tool | Built (Session 69) | Edit existing content |
audit_content tool | Built (Session 69) | Quality audit filters |
find_similar_items tool | Built (Session 69) | Duplicate detection via cosine similarity |
get_content_items tool | Built (Session 69) | Batch fetch by ID array |
| Tool annotations | Complete | All tools annotated with readOnlyHint, destructiveHint, idempotentHint, openWorldHint, title |
| Deferred tool loading | N/A | Client-side concern, not an MCP SDK feature. Current tool count sits at the upper end of recommended range |
structuredContent responses | Planned | Dual output for MCP Apps (content + structuredContent) |
Layer 2: MCP Apps
Section titled “Layer 2: MCP Apps”| Component | Status | Notes |
|---|---|---|
| Search Results App | Planned | Rich result cards with domain/type filters |
| Coverage Matrix App | Built (Session 72) | Interactive taxonomy heatmap with drill-down and gap cards |
| Bid Dashboard App | Built (Session 76, drill-down S81) | Progress bars, deadline countdowns, urgency sorting, drill-down to sections/questions/KB search |
| Reorient Me App | Built (Session 84) | Interactive personal briefing app |
| Intelligence Feed App | Built | Sector intelligence change-report cards scoped to workspace/period (show_intelligence_feed tool) |
| Review Queue App | Planned (future) | Speed-triage cards inside Claude |
| Content Timeline App | Planned (future) | Freshness and activity timeline |
Layer 3: Knowledge Hub Plugin
Section titled “Layer 3: Knowledge Hub Plugin”| Component | Status | Notes |
|---|---|---|
| Plugin structure | Built (Session 66b) | .claude/plugins/knowledge-hub/1.0.0/ |
| 6 commands | Built (Session 66b) | search, briefing, bid-status, coverage, draft-response, digest |
| 5 skills | Built (Session 66b) | search-strategy, procurement-writing, knowledge-synthesis, content-governance, classification |
| CONNECTORS.md | Built (Session 66b) | Documents the ~~knowledge base connector |
| README.md | Built (Session 66b) | Full user-facing documentation |
| settings.template.json | Built (Session 66b) | Personalisation configuration |
| Cowork registry listing | Planned (future) | Currently manual install only |
| CONNECTORS.md | Needs update | Should reference docs/generated/mcp-inventory.md for current tools, resources, prompts |
Layer 4: Claude Code Plugin
Section titled “Layer 4: Claude Code Plugin”| Component | Status | Notes |
|---|---|---|
| CLAUDE.md | Built | Project conventions, architecture, gotchas |
| 10 quality checks | Built | .claude/checks/ (accessibility, design system, etc.) |
| MEMORY.md | Built | Cross-session project context |
| KB-aware agents | Planned (future) | kb-researcher, bid-assistant agents |
| Dedicated plugin structure | Planned (future) | After client pilot |
Claude Bridge (In-App AI Entry Points)
Section titled “Claude Bridge (In-App AI Entry Points)”| Component | Status | Notes |
|---|---|---|
| ClaudePromptButton | Built (Session 99, preserved S109) | Contextual prompt generation + open Claude directly |
| 6 prompt generators | Built (Sessions 99-104) | Browse, item detail, certification review, document diff review, content creation, quality actions |
| Claude-first strategy | Active | All AI interaction routes through Claude via MCP or prompt bridge — no in-app chat sidebar |
AI Service Layer (Shared Foundation)
Section titled “AI Service Layer (Shared Foundation)”| Component | Status | Notes |
|---|---|---|
AI integration points in lib/ai/ | Built (Session 65) | classify, summarise, digest, embed, extract, vision, questions, matching, drafting, quality, tender, errors |
| Server-side skill files | Built (Session 65) | procurement-writing, uk-procurement, classification, governance |
| Skill loader | Built (Session 65) | lib/ai/skills/loader.ts |
| Entity extraction on ingest | Built (Session 67) | Non-blocking, integrated with classification |
| Entity deduplication | Built (Session 67) | lib/entity-dedup.ts canonical name normalisation |
| Content citations tracking | Built (Session 67) | content_citations table + RPCs |
Background Automation
Section titled “Background Automation”| Component | Status | Notes |
|---|---|---|
| Freshness cron (pg_cron) | Built | recalculate-freshness-daily at 03:00 UTC |
| Classification quality cron | Built (S102-S107) | app/api/cron/classification-quality/route.ts — weekly re-classify items with low confidence |
| Coverage alerts cron | Built (S102-S107) | app/api/cron/coverage-alerts/route.ts — weekly gap analysis notifications |
| Freshness transition notifications | Built (S102-S107) | app/api/cron/freshness-transitions/route.ts — daily notifications on freshness transitions |
| Content gap detection | Built (S102-S107) | app/api/cron/content-gaps/route.ts — weekly detection of thin domains |
| Quality score recalculation | Built (S102-S107) | app/api/cron/quality-score/route.ts — daily quality score recalculation |
6. Documentation Hierarchy
Section titled “6. Documentation Hierarchy”When Anthropic ships a new MCP feature and Knowledge Hub adopts it, which doc is updated first? The five-tier hierarchy below answers that, and is the canonical authority for “where does this number/pattern/decision belong”.
The Five-Tier Hierarchy
Section titled “The Five-Tier Hierarchy”| Tier | Doc | Job | When updated |
|---|---|---|---|
| 0 | docs/generated/mcp-inventory.md | Auto-generated truth: tool/resource/prompt counts, names, annotations. | Automatically by bun run generate:mcp-inventory after every lib/mcp/tools/*.ts or lib/mcp/resources.ts change. First (auto). |
| 1 | lib/mcp/CLAUDE.md | Developer hot-path conventions: tool registration patterns, response format, auth, lazy imports, formatters, “adding a new tool” steps. | When the pattern changes (not when individual tools are added). |
| 2 | docs/reference/ai-integration-layers.md (this doc) | Technical layer map, crossover matrix, decision rules, built/planned status. | When a new capability is shipped that adds a row to the crossover matrix (§3) OR changes which layer something lives in OR changes the built/planned status (§5). |
| 3 | docs/reference/ai-integration-strategy.md | Vision, why-we-integrate, decision log, sprint history, effort estimates, presentation-split philosophy. | When a strategic decision is made (new entry in §19 decision log) OR when a vision/positioning point shifts. |
| 4a | docs/client-documentation/Knowledge Hub — Claude Integration Guide.md | User-facing description of tools/apps/plugin in plain language. | When a new user-visible capability ships (new tool, new app, new command). |
| 4b | docs/client-documentation/Knowledge Hub — Platform Overview.md | Top-of-funnel product overview. | Rare. Only when a new pillar of the product ships (e.g. sector intelligence). |
| 5 | docs/product-functionality/ai-integration/* (future) | User journey + technical detail for each AI capability area. | Currently empty. Future state. |
The “New MCP Feature” Drill
Section titled “The “New MCP Feature” Drill”Anthropic ships a new MCP feature. Knowledge Hub adopts it. The order of updates is:
- Code first. Add the tool/resource/prompt/pattern to
lib/mcp/. - Tier 0 (auto): Run
bun run generate:mcp-inventory.docs/generated/mcp-inventory.mdupdates automatically. This is the source of truth for counts and tool names. Nothing else should hard-code these numbers. - Tier 1 (
lib/mcp/CLAUDE.md): If the new feature changes a pattern (e.g. a new annotation, a new response format option, a new auth flow), update the conventions section. If it just adds another tool of an existing pattern, no update. - Tier 2 (this doc,
ai-integration-layers.md): Add a row to the §3 crossover matrix if the new feature is a user-visible capability. Update the §5 built/planned status table. Touch §1 layer descriptions only if the layer model itself changes (rare — the four layers are stable). - Tier 3 (
ai-integration-strategy.md): Add a new entry to the §19 decision log if there was a strategic choice involved (e.g. “we adopted X over Y because…”). Update §2 current-state with one line. Do not duplicate the §3 crossover matrix or §5 status table — link to this doc. - Tier 4a (
Claude Integration Guide): Add the user-facing description in the appropriate category. Replace any hard-coded count with a reference to mcp-inventory.md. - Tier 4b (
Platform Overview): Only if this is a new product pillar. - Tier 5 (
docs/product-functionality/ai-integration/*): Future — when this directory is populated, add a per-feature page.
One-Sentence Summary
Section titled “One-Sentence Summary”Counts come from docs/generated/mcp-inventory.md (auto); patterns from
lib/mcp/CLAUDE.md (dev); the layer map and “where does it live” matrix from
this doc (architect); the why and the decision log from
ai-integration-strategy.md (product); the user-facing narrative from the
client integration guide (client).
Drives-vs-Driven Relationships
Section titled “Drives-vs-Driven Relationships”lib/mcp/CLAUDE.mdandmcp-inventory.mddrive this doc. If the inventory changes, layers.md changes.- This doc drives
ai-integration-strategy.md’s current-state section. If the layer map changes, strategy.md updates §2. ai-integration-strategy.mddrives the client-facing docs’ narrative framing. If a new strategic principle lands, the client docs may need a tone shift.- The client integration guide does not drive anything else — it is downstream.
lib/mcp/CLAUDE.mdis the only doc that should ever lead a change. Everything else is reactive.
Quick Reference: Where Things Live in the Codebase
Section titled “Quick Reference: Where Things Live in the Codebase”| Layer | Location | Key files |
|---|---|---|
| Layer 1 (MCP Server) | lib/mcp/ | tools/ (category files), resources.ts, formatters/, auth.ts |
| Layer 1 (MCP Route) | app/api/mcp/ | [transport]/route.ts |
| Layer 1 (OAuth) | app/oauth/, app/.well-known/, app/api/oauth/ | Consent UI, RFC 9728, decision handler |
| Layer 2 (MCP Apps) | mcp-apps/ | coverage-matrix/, bid-dashboard/, reorient-me/, lib/mcp/app-bundles.ts |
| Layer 3 (Plugin) | .claude/plugins/knowledge-hub/1.0.0/ | README.md, commands/, skills/, .mcp.json |
| Layer 4 (Claude Code) | .claude/, root | CLAUDE.md, .claude/checks/, MEMORY.md |
| Claude Bridge | lib/claude-prompts.ts, components/claude-prompt-button.tsx | Contextual prompt generators, open-Claude buttons |
| AI Service Layer | lib/ai/ | classify.ts, summarise.ts, digest.ts, embed.ts, etc. |
| Server-side skills | lib/ai/skills/ | procurement-writing.md, uk-procurement.md, classification.md, governance.md |
Summary: The One-Sentence Version of Each Layer
Section titled “Summary: The One-Sentence Version of Each Layer”- MCP Server — gives Claude the ability to access your data
- MCP Apps — give Claude the ability to show you visual interfaces
- Knowledge Hub Plugin — gives Claude the expertise to use your data well
- Claude Code Plugin — gives Claude the context to develop the product
The MCP server is the foundation. Everything else builds on it. In-app AI interaction is handled via the ClaudePromptButton bridge, which generates contextual prompts and opens Claude directly rather than embedding a separate chat sidebar.
Reference document produced: 9 March 2026, updated 7 April 2026 (S151 Task 17b
— restructure: counts referenced from inventory, documentation hierarchy
added). Source material: docs/reference/ai-integration-strategy.md,
lib/mcp/tools/, lib/mcp/resources.ts, docs/generated/mcp-inventory.md,
.claude/plugins/knowledge-hub/1.0.0/.
Sync drift — 02/07/2026
Section titled “Sync drift — 02/07/2026”- [tool]
search_knowledge_baseandsearch_qa_librarycollapsed into a singlefindtool (ID-71.x consolidation,lib/mcp/tools/search.ts); §1 Layer 1 and the §3 crossover matrix still name both as separate tools. - [tool]
get_dashboard_summaryretired intowhats_in_my_queueandwhere_are_we_exposed(ID-71.9 / ID-71.8,lib/mcp/tools/dashboard.ts); §3 crossover matrix still namesget_dashboard_summary. - [tool]
get_freshness_report,get_coverage_gaps,get_quality_summary, andaudit_contentretired intowhere_are_we_exposed(ID-71.8,lib/mcp/tools/dashboard.ts); §3 crossover matrix and §5 AI Service Layer still name them. - [tool]
find_similar_itemscollapsed into thefindtool’ssimilar_toparam; a newfind_duplicatestool exists (lib/mcp/tools/search.ts); §3 crossover matrix still namesfind_similar_items. - [tool]
list_active_bids,get_bid_detail, andget_bid_questionrenamed tolist_active_procurement,get_procurement_detail(procurement umbrella,lib/mcp/tools/procurement.ts); §3 crossover matrix and §1 still use the bid names. - [tool]
get_content_item/get_content_itemsrenamed toget(lib/mcp/tools/content.ts); §3 crossover matrix still namesget_content_itemandget_content_items. - [lib]
lib/entity-dedup.tspath renamed tolib/entities/entity-dedup.ts; §5 AI Service Layer row “Entity deduplication” cites the old path. - [tool] Bid Dashboard MCP App’s HTML bundle is
FORM_DASHBOARD_HTMLand its trigger tool isshow_procurement_dashboard(lib/mcp/tools/apps.ts,lib/mcp/app-bundles.ts); §1 Layer 2 and §3 still call it “Bid Dashboard” / implyshow_bid_dashboard. - [route] Five live
app/api/cron/*/route.tsroutes are omitted from §5 Background Automation:datapath-watch,intelligence-cleanup,intelligence-poll,process-queue,review-cadence.