AI Integration — User Journeys

AI Integration — User Journeys

Last verified: Session 210 (29 April 2026). Refresh covers S195-S209 + production-readiness S10-S13. Tool, resource, and prompt counts are auto-generated — see docs/generated/mcp-inventory.md.

Overview

The AI Integration area has two distinct user populations:

1. Web app users (viewer / editor / admin) interact with AI as invisible infrastructure. Classification, summaries, embeddings, and quality scores appear as platform features — never branded as “AI”. The only AI surface a non-admin will ever see is the classification_confidence percentage in the Source Information accordion (editor+) and the optional “Continue in Claude” ClaudePromptButton bridge.
2. Claude users (Claude Desktop, Claude.ai, Cowork, Claude Code) interact with Canonical through the MCP server — an outcome-grouped tool set plus resources, prompts, and 4 MCP Apps (counts auto-generated; see docs/generated/mcp-inventory.md). They search, classify, create, and visualise KB data inside Claude. The surface is organised so callers reach for an outcome, not a tool name: find for retrieval, where_are_we_exposed for gaps/freshness, whats_in_my_queue for review work, get for fetching one or many items.

Admins also have access to the Provenance route (/provenance), the only surface where AI mechanism data — model names, token counts, costs, classification reasoning — is exposed (per the AI-Visibility Policy admin carve-out).

Entry Points

Entry Point	Route / Surface	Accessible By
Item detail — Source Information	/item/[id] accordion	Editor, Admin
Provenance route	/provenance (5 tabs)	Admin only
MCP server	/api/mcp/mcp (Streamable HTTP transport)	Authenticated MCP clients
Settings — Connections	/settings connector setup	All roles
ClaudePromptButton bridge	Inline buttons across browse / item / certification UI	All roles
Manual classify	POST /api/items/[id]/classify	Editor, Admin
Manual summarise	POST /api/summaries/generate	Editor, Admin
MCP Apps (inside Claude)	show_* tools	Authenticated MCP clients

---

User Journeys

Journey 1: Editor Creates Content via the MCP Connector

Actor: Editor or admin using Claude Desktop / Claude.ai with the Knowledge Hub connector enabled. Goal: Add a new policy document to the KB and have it indexed for retrieval. Preconditions: OAuth bearer token in place (connector configured via Settings → Connections).

Steps

1. User asks Claude to create the item.
   • The user pastes the policy markdown into the Claude conversation and requests “Add this to the KB as a policy in domain X.”
   • Claude calls create_content_item with the appropriate content_type, primary_domain, optional primary_subtopic, and one of the typed provenance fields (source_url, source_file, or source_document_id — S205 WP-A1 §1.21).
2. Server runs the full ingest pipeline.
   • Tool: lib/mcp/tools/content.ts create_content_item handler
   • Validates input (Zod schemas), resolves dedup, then calls classifyContent() (Pass 1), generateSummary(), generateEmbedding(), regenerateChunks(), and recordPipelineRun() in a single request.
   • Writes the row with ingest_source = 'mcp_create' (S207 WP-A4) so the ensure_v1_history_at_commit() trigger emits change_reason = 'initial_ingest'.
3. Claude reports back.
   • Markdown response confirms creation, surfaces the suggested title, domain/subtopic, primary entities, and chunk count.
   • Structured content payload mirrors the data for programmatic chaining.
4. Item is searchable immediately.
   • The new row is reachable through the find tool (across its type / scope / granularity branches) and the web app’s browse view.

Variations

• Draft mode: Editor sets publication_status: "draft". Embedding and chunk generation are skipped; the row is excluded from search and visible only in the review queue’s Drafts filter.
• Auth failure (viewer caller): pipeline_runs row written with status 'failed', error message 'Permission denied', via lazy-imported service-role client (S206 WP4 / S207 OPS-38).
• Insert failure (DB constraint): Pre-success failed-insert path also emits a pipeline_runs row with status='failed' and phase='pre_success' in the result payload (S207 OPS-39).

Edge Cases

• Suspected duplicate: Soft-block; row inserted with dedup_status='suspected_duplicate', metadata.suspected_duplicate_of pointing to the existing item (S184 WP1 D1).
• Admin override: skip_dedup=true bypasses the check (admin only; silently ignored for non-admin callers).
• Missing typed provenance: If the caller passes the legacy source_document field, the request fails with a Zod error advertising the three typed replacements. Zod 4 strip mode is bypassed via .refine() so the error is enforced (not silently dropped).

---

Journey 2: Completing a Form Response with Cited Sources

Actor: A user completing a form (e.g. a UK public-procurement tender response) via the /kb:draft-response plugin command in Cowork or Claude.ai. Goal: Draft a form response with citations back to the KB. Preconditions: Plugin installed, MCP connector configured, the form question text is to hand.

Steps

1. User invokes /kb:draft-response "{question text}".
   • Command file: .claude/plugins/knowledge-hub/1.0.0/commands/draft-response.md
2. Plugin orchestrates skills + tools.
   • The search-strategy skill decomposes the question and calls the find tool, choosing the appropriate type / scope / granularity branch (the single retrieval entry that replaced the former search trio).
   • The completing-forms skill enforces UK procurement conventions and word limits (generalised from the former bid-writing skill — procurement is the first form type).
   • The knowledge-synthesis skill deduplicates results and assesses confidence.
3. Claude returns a draft with citations.
   • Each citation references a content item ID + title.
   • Confidence postures: confident (multiple high-similarity matches), cautious (single source or stale data), unmatched (no KB content — prompts the user to flag a content gap).
4. User accepts → Claude calls cite_content.
   • Each cited content item gets a citations row linking the form response to the source item, enabling get_content_effectiveness reporting later.

Variations

• Without the connector: The plugin command works in standalone mode — the user pastes content into Claude and the same skills apply, but no live KB search.
• Via web app /procurement/[id]/responses: AI-driven drafting also runs through runDraftingPipeline() server-side (/api/procurement/[id]/responses/draft). The user never sees model names — the draft simply appears in the editor.

Edge Cases

• No matching KB content: Claude reports unmatched, suggests the user invoke the content-creation skill, and pre-fills a draft skeleton.
• Stale citations: Synthesis skill warns the user if cited items have freshness ∈ {stale, expired} or below-threshold quality scores.

---

Journey 3: Admin Audits Per-Item Provenance

Actor: Admin investigating “why did this item get classified as X?” Goal: Inspect classification confidence, model used, token cost, and reasoning for a specific item. Preconditions: Admin role; item ID known.

Steps

1. Admin navigates to /provenance.
   • Route: app/provenance/provenance-content.tsx
   • Role gate: useUserRole() client-side + getAuthorisedClient(['admin']) on the API. Non-admins see the AccessDenied component.
2. Admin opens the Per-item tab.
   • Tab: components/provenance/per-item-tab.tsx
   • Pastes a UUID; route GET /api/provenance/item/[id] returns:
     • Classification block: confidence (decimal + percentage), domain/subtopic slugs + names, full classification_reasoning text.
     • Processing block: model name, input/output tokens, cost (via lib/provenance/pricing.ts), processed timestamp.
     • Drafting block: if any AI form responses cite this item, lists attribution with PIPELINE_SYSTEM_USER_ID promoted to “Knowledge Hub”.
     • Review Schedule block (S207 §5.5 Phase 3 T4): next review date, review cadence (Every {N} days ({N/30} months)), last reviewed (verified_at).
3. Admin cross-references with Pipeline Health.
   • Tab: components/provenance/pipeline-health-tab.tsx
   • Keyset-paginated list of pipeline_runs rows with time-range + kind filters and a 20K truncation guard. Failure drawer shows the full error message for any failed run.
4. Admin downloads PDF audit.
   • GET /api/admin/provenance/export/verification-history produces an A4 PDF (via @react-pdf/renderer) of day-grouped verification events. The export call itself is logged via recordPipelineRun().

Variations

• Audit tab: 1:1 lift of ActivitySection from /settings; same ActivityFeed component. Hosts the PDF export trigger.
• Cost tab: Stub showing aggregate pipeline_runs.cost. Labelled “Interim — Wave B”.
• Disputes tab: Stub showing classification_disputes rows. Labelled “Interim — Wave C”.

Edge Cases

• Item never classified: Per-item tab returns classified_at: null; classification block shows “Not classified” rather than empty values.
• Pipeline run truncation: When more than 20K runs match filters, the Pipeline Health tab returns the most recent 20K with a banner indicating truncation.

---

Journey 4: Editor Reviews Content Quality with Cadence Awareness

Actor: Editor processing the review queue. Goal: Verify items whose review cadence has elapsed. Preconditions: next_review_date and review_cadence_days configured on items (set via the Review Cadence Editor on item detail).

Steps

1. Editor opens /review.

   • Page: app/review/page.tsx

   • The ReviewCadenceCard (S206 §5.5 Phase 3 T1) shows count pills for overdue / due-soon items per the four-band matrix:

     Band	Badge
     governance_review_status='review_overdue'	”Review overdue” (red)
     next_review_date ≤ 14 days inclusive	”Review due {DD/MM/YYYY}” (amber)
     > 14 ≤ 30 days inclusive	Muted text-only badge
     > 30 or NULL	No badge

2. Editor toggles “Overdue reviews” filter.
   • Component: components/review/review-filters.tsx (S205 §5.5 Phase 3 T2). Toggle changes the route’s filter from verified_at IS NULL to verified_at.is.null,governance_review_status.eq.review_overdue so verified-but-overdue rows surface.
3. Editor verifies an item.
   • POST /api/review/action with action: "verify". Sets verified_at and verified_by; resolves any open review_needed flags.
   • §5.5 Phase 2 T2 cadence-driven auto-renewal: if review_cadence_days is set, next_review_date advances to GREATEST(current, today) + cadence (symmetric with the governance approve path).
4. Editor edits the cadence directly on item detail.
   • Component: components/content/review-cadence-editor.tsx (S206 §5.5 Phase 3 T3). Provides a date picker plus 5-preset Select (No recurring review / Every 3 months / Every 6 months / Every 12 months / Custom…). Custom range [1, 1095] days; client-side validation rejects out-of-range before POST.
   • Self-contained TanStack useMutation PATCHes /api/items/:id with field='next_review_date' or 'review_cadence_days'.

Variations

• Read-only view: Reader view hides the Cadence Editor via {!readOnly && ...} guard in metadata-sidebar.tsx.
• MCP-driven: whats_in_my_queue (the single faceted queue) accepts facet: "governance" plus include_overdue + status_filter (pending / review_overdue / all) so MCP callers triage the same queue. The find tool accepts overdue_review + review_due_within_days filters on its chunk-granularity branch for retrieval scoped to cadence-elapsed items.

Edge Cases

• Quality drop on verify: S208 §5.5 Phase 5 cadence-compliance scorer applies a penalty to the freshness sub-score when next_review_date is populated. Scoring is preserved exactly for items WITHOUT cadence tracking.

---

Journey 5: Claude User Visualises Coverage via MCP Apps

Actor: Knowledge worker using Claude Desktop / Claude.ai. Goal: Spot domain coverage gaps without leaving Claude. Preconditions: MCP connector configured.

Steps

1. User asks Claude “where are our biggest coverage gaps?”
   • Claude calls show_coverage_matrix (read-only MCP App trigger).
2. Server returns the Coverage Matrix App.
   • Tool: lib/mcp/tools/apps.ts (registerAppTool wrapper)
   • Resource: ui://coverage-matrix/app.html — Vite single-file build inlined from lib/mcp/app-bundles.ts.
3. App renders inline in Claude’s conversation.
   • The HTML card calls where_are_we_exposed (the consolidated five-layer exposure tool that absorbed the former freshness / quality / coverage-gap reads) to populate the heatmap.
   • Colour-coded cells (Warm Meridian semantic tokens) show domain × freshness intersection counts. Drill-down opens gap cards.
4. User clicks a gap card → Claude offers to create content.
   • Plugin command /kb:coverage or skill content-creation is invoked via natural-language follow-up.

Variations

• Procurement Dashboard App: show_procurement_dashboard triggers the same lifecycle with ui://form-dashboard/app.html. Drill-down to form sections + KB retrieval (via find) with confidence badges.
• Reorient Me App: show_reorient_me produces a personal briefing card with urgent items, active forms, recent work, team changes.
• Intelligence Feed App: show_intelligence_feed (workspace-scoped) shows sector intelligence digest cards filtered by period.

Edge Cases

• Empty staging DB: All four apps degrade gracefully — the contract test mcp-app-contracts.test.ts enforces type parity between formatter interfaces and app types so an empty array doesn’t break rendering.

---

Journey 6: Admin Configures the Claude Connector

Actor: First-time admin onboarding to the MCP integration. Goal: Connect Claude Desktop to Canonical. Preconditions: Admin role on a deployed environment.

Steps

1. Admin opens /settings → Connections.
   • Page: app/settings/page.tsx
2. Admin follows the connector setup.
   • Public OAuth metadata endpoints discoverable via app/.well-known/oauth-protected-resource/route.ts (RFC 9728).
   • Consent UI: app/oauth/consent/page.tsx.
   • Decision handler: app/api/oauth/decision/route.ts.
3. Claude Desktop polls /api/mcp/mcp.
   • First request returns 401 with a WWW-Authenticate header pointing to the Protected Resource Metadata.
   • OAuth flow completes, bearer token cached in Claude Desktop.
4. Admin verifies via /kb:briefing.
   • Plugin command returns the reorientation briefing — confirms tools and resources are reachable.

Variations

• Cowork: Same flow; Cowork is an MCP-compatible client.
• Claude Code (development): Plugin marketplace handles install. After pushing plugins to remote, git pull in ~/.claude/plugins/marketplaces/{name}/ to refresh.

Edge Cases

• Plugin uninstall asymmetry: /plugin uninstall may leave stale disable overrides in settings.local.json. Run uninstall on each scope (user, project) explicitly.

---

Role Permissions Summary

Action	Viewer	Editor	Admin
Search KB via MCP	Yes	Yes	Yes
Read-only MCP tools (get/find/list/audit/show)	Yes	Yes	Yes
classify_content MCP tool	No	Yes	Yes
generate_summary MCP tool	No	Yes	Yes
create_content_item / update_content_item	No	Yes	Yes
delete_content_item MCP tool	No	No	Yes
supersede_content_item MCP tool	No	No	Yes
assign (owner, one or many) / update_publication_status	No	Yes	Yes
Provenance route (/provenance all tabs)	No	No	Yes
classification_confidence text in Source Information	No	Yes	Yes
ClaudePromptButton bridge (open Claude)	Yes	Yes	Yes
Settings → Connections (configure connector)	Yes (read)	Yes (read)	Yes (write)

---

Current Limitations

• No in-app chat sidebar. All AI-assisted interactions either run as invisible background processing or route the user to Claude via the ClaudePromptButton bridge. The CopilotKit sidebar that previously implemented an in-app chat experience was fully removed in S109.
• Provenance is admin-only. Editors can see classification_confidence as plain text on /item/[id], but cannot access model names, token counts, costs, or classification reasoning.
• MCP Apps are read-mostly. All four shipped apps invoke read-only tools. Write actions remain in the web app or via direct MCP write tools.
• Plugin commands assume the connector is configured. Standalone mode (paste content into Claude) works but lacks live KB search.

Related Documentation

• Technical reference: docs/product-functionality/ai-integration/technical.md
• Workflows: docs/product-functionality/ai-integration/workflows.md
• AI integration layers: docs/reference/ai-integration-layers.md
• AI integration strategy: docs/reference/ai-integration-strategy.md
• AI visibility policy: docs/reference/ai-visibility-policy.md
• Classification prompt: docs/reference/classification-prompt.md
• Data entry points: docs/reference/data-entry-points.md