@hippo-digital/hippocampus 1.0.0-rc.1

package/docs/agentic-patterns-to-port.md

@@ -0,0 +1,273 @@
+# Agentic Patterns To Port From NCRS
+
+Source reviewed:
+
+- `/Users/mattfielding/clawd/projects/ncrs-prototype-agentic/.github`
+- `/Users/mattfielding/clawd/projects/ncrs-prototype-agentic/docs`
+- `/Users/mattfielding/clawd/projects/ncrs-prototype-agentic/artefacts`
+
+## Recommendation
+
+Port the operating model, not the NCRS clinical content.
+
+The strongest transferable pattern is a Copilot-discoverable agent workspace:
+
+- `.github/copilot-instructions.md`
+- `.github/instructions/*.instructions.md`
+- `.github/legacy/prompts/*.prompt.md`
+- `.github/agents/*.md`
+- `docs/` for architecture and workflow rules
+- `artefacts/` for generated outputs, screenshots and audits
+
+The knowledge base repo already has archived prompts in `.github/legacy/prompts`. The next useful work is to keep repo-wide Copilot instructions, focused custom agents and the portable skill catalog aligned.
+
+## High-value ports
+
+### 1. Copilot instructions
+
+NCRS has `.github/copilot-instructions.md` loaded into every Copilot chat.
+
+Port as:
+
+```text
+.github/copilot-instructions.md
+```
+
+Purpose:
+
+- tell Copilot this is an NHS Prototype Kit knowledge base
+- define source model rules
+- require validation after source edits
+- require NHS Prototype Kit conventions
+- forbid real patient data
+- prefer source-model changes over hard-coded page changes
+
+Why it matters:
+
+Prompts are optional. Copilot instructions are ambient. They reduce bad default behaviour.
+
+### 2. Focused custom agents
+
+NCRS consolidated overlapping agents into four roles:
+
+- `@prototype-builder`
+- `@screenshot-runner`
+- `@accessibility-tester`
+- `@workflow-orchestrator`
+
+Port as:
+
+```text
+.github/agents/README.md
+.github/agents/knowledge-builder.md
+.github/agents/prototype-builder.md
+.github/agents/screenshot-runner.md
+.github/agents/accessibility-tester.md
+.github/agents/workflow-orchestrator.md
+```
+
+Adaptation:
+
+- add `@knowledge-builder` because this repo's primary product is source-model maintenance
+- keep `@prototype-builder` for routes/views/screens
+- keep `@screenshot-runner` and `@accessibility-tester` for review loops
+- keep `@workflow-orchestrator` to coordinate build → validate → screenshot → accessibility → summary
+
+### 3. Instruction files
+
+NCRS uses `.github/instructions/*.instructions.md` for auto-attached guidance.
+
+Port a smaller set:
+
+```text
+.github/instructions/knowledge-source.instructions.md
+.github/instructions/nhs-prototype-kit.instructions.md
+.github/instructions/nhs-frontend.instructions.md
+```
+
+Do not copy the huge generated NHS component reference yet. It is useful but heavy. Start with concise instructions and add component reference later if Copilot needs it.
+
+### 4. Agent workflow docs
+
+NCRS has:
+
+- `docs/AGENT-WORKFLOW.md`
+- `docs/PROMPT-ARCHITECTURE-GUARDRAILS.md`
+- `docs/CUSTOM-AGENTS-USAGE.md`
+
+Port as:
+
+```text
+docs/agent-workflow.md
+docs/prompt-architecture-guardrails.md
+docs/custom-agents-usage.md
+```
+
+Adaptation:
+
+- prioritise knowledge base source edits
+- require `npx hippocampus validate`
+- define when to add source records versus Nunjucks screens
+- define expected output locations
+- require delivery summaries after orchestrated runs
+
+### 5. Artefact structure
+
+NCRS separates generated outputs under `artefacts/`.
+
+Port as:
+
+```text
+artefacts/
+  scenarios/
+  screenshots/
+  accessibility/
+  delivery-summaries/
+  generated-docs/
+```
+
+Keep `hippocampus/source` as the source of truth. Use `artefacts/` only for generated/derived outputs and review evidence.
+
+### 6. Screenshot and accessibility loops
+
+NCRS has dedicated screenshot and accessibility agent outputs:
+
+- `artefacts/screenshots/<YYYY-MM-DD>/manifest.md`
+- `artefacts/accessibility/`
+
+Port this because the knowledge base needs reviewable artefacts, not just running pages.
+
+First implementation can be documentation-only agents. Later add scripts if needed.
+
+### 7. Staged prompt workflow
+
+NCRS uses staged prompts:
+
+1. scenario and problem statement
+2. personas
+3. journeys
+4. prototype build
+5. screenshots/accessibility
+
+Port the staged shape, but adapt it:
+
+1. source-model slice
+2. user needs and scenarios
+3. journeys and blueprint view model
+4. prototype screens
+5. generated documentation
+6. screenshots/accessibility
+
+The current prompt pack partly covers this already. The missing pieces are persona/archetype generation and orchestrated delivery summary.
+
+## Medium-value ports
+
+### Persona generation
+
+NCRS has a substantial persona-generation prompt for M365 Copilot Researcher.
+
+Port a lighter version for the knowledge base:
+
+- generate user groups and archetypes
+- link each archetype to needs and scenarios
+- avoid patient/public persona generation unless the service slice is patient-facing
+- ask for evidence or mark assumptions
+
+This would extend the current model, because `users.json` is currently user groups, not full personas.
+
+### Journey map artefact output
+
+NCRS build prompts require generated journey maps in Markdown and JSON.
+
+Port this as:
+
+```text
+artefacts/journey-maps/<journey-id>.md
+artefacts/journey-maps/<journey-id>.json
+```
+
+This is useful because the knowledge base can then preserve a review snapshot separate from live source data.
+
+### Delivery summaries
+
+NCRS orchestrator writes:
+
+```text
+docs/<YYYY-MM-DD>-delivery-summary.md
+```
+
+Port this as:
+
+```text
+artefacts/delivery-summaries/<YYYY-MM-DD>-<topic>.md
+```
+
+This keeps generated delivery notes separate from source documentation.
+
+## Low-value or defer
+
+### Clinical FHIR fixture workflow
+
+Do not port now.
+
+It is powerful but NCRS-specific and would pull the knowledge base toward clinical data testing before the service design model is proven.
+
+Revisit only if a slice needs structured clinical data provenance, source contradiction or fixture generation.
+
+### Large generated NHS Frontend component reference
+
+Useful, but heavy.
+
+Start with concise NHS Frontend instructions. Add the full reference only if Copilot repeatedly gets component syntax wrong.
+
+### Dependabot and release workflows
+
+Defer until there is a GitHub remote and a clearer package/release direction.
+
+## Suggested next commits
+
+### Commit 1
+
+`Add Copilot instructions and knowledge source guidance`
+
+Files:
+
+- `.github/copilot-instructions.md`
+- `.github/instructions/knowledge-source.instructions.md`
+- `.github/instructions/nhs-prototype-kit.instructions.md`
+- `docs/agent-workflow.md`
+- `docs/prompt-architecture-guardrails.md`
+
+### Commit 2
+
+`Add focused custom agents for knowledge base workflow`
+
+Files:
+
+- `.github/agents/README.md`
+- `.github/agents/knowledge-builder.md`
+- `.github/agents/prototype-builder.md`
+- `.github/agents/screenshot-runner.md`
+- `.github/agents/accessibility-tester.md`
+- `.github/agents/workflow-orchestrator.md`
+- `docs/custom-agents-usage.md`
+
+### Commit 3
+
+`Add generated artefact workspace`
+
+Files:
+
+- `artefacts/README.md`
+- `hippocampus/source-artefacts/scenarios/README.md`
+- `artefacts/screenshots/README.md`
+- `artefacts/accessibility/README.md`
+- `artefacts/delivery-summaries/README.md`
+- `artefacts/generated-docs/README.md`
+
+## Best next move
+
+Start with commit 1.
+
+Copilot instructions and source guidance will improve every later prompt and agent. Agents are useful, but ambient instructions are more foundational.
+

package/docs/colour-pairings.md

@@ -0,0 +1,41 @@
+# Service blueprint colour pairs
+
+Reference palette for colour-coding categories in service blueprint style
+visualisations (lanes, entity types, post-it style groupings). Each pairing
+is a saturated "post-it" colour plus a pale background tint meant to be used
+together - the post-it colour for text/borders/accents, the tint for a
+light fill behind it.
+
+Source: NHS colour pairings reference (supplied 2026-09-04).
+
+| Name | Post-it | Background tint |
+| --- | --- | --- |
+| Dark blue | `#003087` | `#E6EAF3` |
+| NHS blue | `#005EB8` | `#E6EFF8` |
+| Bright blue | `#0072CE` | `#DEEEFA` |
+| Light blue | `#41B6E6` | `#ECF8FD` |
+| Aqua blue | `#00A9CE` | `#E6F6FA` |
+| Aqua blue, dark | `#00758F` | `#E6F6FA` |
+| Aqua green | `#00A499` | `#E6F6F5` |
+| Aqua green, dark | `#00726B` | `#E6F6F5` |
+| Light green | `#78BE20` | `#EDF9E8` |
+| Dark green | `#006747` | `#E6F5EB` |
+| Warm yellow | `#FFB81C` | `#FFF9E8` |
+| Orange | `#ED8B00` | `#FDF3E6` |
+| Orange, dark | `#8E5300` | `#FDF3E6` |
+| Dark pink | `#7C2855` | `#F2EAEE` |
+| Purple | `#330072` | `#EBE6F1` |
+
+## Where this applies in Hippocampus
+
+Several existing views already colour-code entity types or categories and
+should draw from this palette rather than ad-hoc hex values when they're
+next touched:
+
+- `node_modules/@hippo-digital/hippocampus/views/hippocampus/graph.html` / `evidence-impact.html` - `.knowledge-graph__node--{type}` border colours (`node_modules/@hippo-digital/hippocampus/assets/hippocampus.scss`), and `node_modules/@hippo-digital/hippocampus/views/hippocampus/trace.html`'s matching `.knowledge-trace-item__type--{type}` badges (same colour set, same reason - one entity, one colour, everywhere it appears). Within `.knowledge-admin-theme`: User = NHS blue `#005eb8`, Evidence = Dark pink `#7c2855`, Journey/Screen/Decision = Warm yellow `#ffb81c` (all three already matched this palette exactly, so left as-is), Scenario = Purple `#330072` (was `#d5281b`, a red not in this palette at all), Need = Dark green `#006747` (was `#007f3b`, close but not exact).
+- Pain point severity (`.knowledge-tagged-item--{severity}` in `node_modules/@hippo-digital/hippocampus/assets/hippocampus.scss`, rendered by `_blueprint-cell.njk`) uses Orange, dark for high and Orange for medium within `.knowledge-admin-theme` - deliberately not Warm yellow, since that already means Journey/Screen/Decision in the graph and trace views above. The default (non-themed) colours stay the original traffic-light red/amber, used outside the admin theme.
+- `_blueprint-controls.njk`'s lens groupings, the blueprint mini-map (`.knowledge-lens-btn`, `.knowledge-blueprint-minimap__marker`), the blueprint/matrix boundary dividers (`.knowledge-boundary`, `.knowledge-matrix__boundary`, e.g. "Line of visibility"), the journey page's timeline (`.knowledge-timeline__item`), and the trace tree's connecting line/markers/selected-item highlight (`.knowledge-trace-timeline::before`, `.knowledge-trace-item__marker`, `.knowledge-trace-item--selected`) all use Aqua green, dark - the same accent as the rest of `.knowledge-admin-theme` - rather than a separate pairing, since they're theme chrome rather than a data category. Nested/child trace markers keep their existing neutral grey rather than picking up the accent, so "already seen" branches stay visually de-emphasised.
+- `.knowledge-graph-summary` (the stat tiles at the top of the graph, research, project and evidence-impact views) uses the full Aqua green, dark pairing - post-it `#00726b` as the left-border accent, tint `#e6f6f5` as the tile background - the one place so far using a pairing exactly as the reference sheet intends (accent plus matching light fill), rather than just swapping an accent colour on its own.
+- `.knowledge-confidence-tag--{level}` (`node_modules/@hippo-digital/hippocampus/views/hippocampus/user.html`) is Evidence's confidence rating (high/medium/low), a different scale from pain-point severity, so it deliberately uses a different colour family - Aqua green (`#00726b` on tint `#e6f6f5`) for high, Aqua blue, dark (`#00758f` on tint `#e6f6fa`) for medium - so the two ratings don't read as the same thing when they appear near each other. Low stays a plain neutral grey rather than a pairing, to signal "uncertain" rather than draw attention.
+
+Not a strict rule - pick the pairing whose hue best fits the category being coded, and keep the same category using the same pairing everywhere it appears (that consistency matters more than which exact pairing is chosen).

package/docs/components.md

@@ -0,0 +1,52 @@
+# Knowledge Base Components
+
+Reusable Nunjucks macros live in `node_modules/@hippo-digital/hippocampus/views/hippocampus/components`.
+
+## Current Macros
+
+### Summary cards
+
+File: `node_modules/@hippo-digital/hippocampus/views/hippocampus/components/_summary-card.njk`
+
+Use `summaryCard(title, body, href, meta)` for dashboard-style links to generated artefacts.
+
+### Lists
+
+File: `node_modules/@hippo-digital/hippocampus/views/hippocampus/components/_list.njk`
+
+Use:
+
+- `bulletList(items, emptyText)` for repeated bullet lists
+- `plainList(items, emptyText)` for simple linked or unbulleted lists
+
+These macros handle empty states consistently.
+
+### Journey steps
+
+File: `node_modules/@hippo-digital/hippocampus/views/hippocampus/components/_journey-step.njk`
+
+Use `journeyStep(step, knowledge)` when rendering journey timeline items. It keeps linked prototype screens and linked user needs in one place.
+
+### Blueprint cells
+
+File: `node_modules/@hippo-digital/hippocampus/views/hippocampus/components/_blueprint-cell.njk`
+
+Use `renderCell(step, laneKey)` in stacked and matrix blueprint views. It maps blueprint lane keys onto the correct content treatment.
+
+### Blueprint controls
+
+File: `node_modules/@hippo-digital/hippocampus/views/hippocampus/components/_blueprint-controls.njk`
+
+Use `renderBlueprintControls(lanes)` on the stacked blueprint view to render the lens-preset buttons (All/Executive/Technical/Risk) and per-lane show/hide checkboxes. Each lane's `lenses` array (set in `buildBlueprintViewModel`) drives which lens presets show it; the buttons and checkboxes are wired up client-side in `node_modules/@hippo-digital/hippocampus/assets/javascript/blueprint.js`.
+
+### Blueprint mini-map
+
+File: `node_modules/@hippo-digital/hippocampus/views/hippocampus/components/_blueprint-minimap.njk`
+
+Use `renderBlueprintMinimap(steps)` on the stacked blueprint view to render a sticky step-navigation rail. `node_modules/@hippo-digital/hippocampus/assets/javascript/blueprint.js` highlights the current step on scroll via `IntersectionObserver`.
+
+## Editing Rules
+
+- Add a macro when markup is repeated across generated artefact views.
+- Keep macros presentational. Source shaping belongs in `node_modules/@hippo-digital/hippocampus/lib/load-knowledge.js`.
+- Run `npx hippocampus validate` and `npx hippocampus doctor` after changing components.

package/docs/copilot-ncrs-research-curator-agent.md

@@ -0,0 +1,298 @@
+# NCRS Research Curator Copilot Agent
+
+This agent is intended to connect to NHS SharePoint research material and produce reviewable documents that are a good fit for Hippocampus ingestion.
+
+It should not directly mutate Hippocampus source data. Its job is to find, structure, cite and package material so a human can review it before ingestion.
+
+## Recommended Agent Name
+
+NCRS Research Curator
+
+## Purpose
+
+Help service designers, researchers and product teams turn scattered NCRS SharePoint material into structured, evidence-backed documents that can be reviewed and ingested into Hippocampus.
+
+The agent should support two lanes:
+
+- **Research ingestion**: research rounds, participants, findings, insights and design actions.
+- **Project context ingestion**: service overview, purpose, vision, problem statements, policy context, constraints, channels, risks, milestones and key facts.
+
+## Knowledge Sources
+
+Connect the agent only to approved NCRS SharePoint locations, for example:
+
+- research reports
+- show-and-tell decks
+- interview notes
+- usability testing notes
+- service maps
+- journey maps
+- policy and governance summaries
+- decision logs
+- design history decks
+- prototype review documents
+
+Prefer narrower SharePoint folders over a broad tenant-wide connection.
+
+## Core Instruction
+
+Paste this into the custom agent instructions:
+
+```text
+You are the NCRS Research Curator.
+
+Your job is to help prepare NHS service design and user research material for Hippocampus ingestion.
+
+Hippocampus is a structured project memory. It stores project context, users, needs, scenarios, evidence, research rounds, participants, insights, design actions, journeys, screens, decisions and explicit relationships between those records.
+
+You must not invent findings, sources, participant evidence, dates, decisions or relationships.
+
+You must use only the connected SharePoint material and the user’s current prompt. If evidence is weak, missing or ambiguous, say so.
+
+Your main outputs are reviewable documents, not final source data. A human must review the document before it is ingested.
+
+Always separate:
+
+1. Project context
+   Purpose, vision, problem statement, service proposition, policy context, constraints, channels, risks, milestones and source facts.
+
+2. Research material
+   Research rounds, participants, findings, insights, evidence, design actions and recommendations.
+
+3. Unknown or weak material
+   Claims that need review, missing source details, unsupported assumptions, duplicate or conflicting findings.
+
+For every claim, include source detail:
+
+- source document title
+- SharePoint link if available
+- page, slide, heading or section
+- date if available
+- author or team if available
+
+Use UK English. Use "artefact" consistently.
+
+When producing a document for Hippocampus ingestion, use the exact output templates provided in your instructions. Keep the structure stable so downstream tools can extract it.
+```
+
+## Conversation Starters
+
+Use these starter prompts in Copilot Studio:
+
+- Find NCRS research material about a specific user group and prepare an ingestion-ready research summary.
+- Turn this SharePoint folder into a Hippocampus project context draft.
+- Compare these research decks and identify repeated insights, contradictions and gaps.
+- Create an evidence-backed design action summary from these research notes.
+- Check whether this material is ready to ingest into Hippocampus.
+
+## Research Output Template
+
+Use this when the source material is a research round, interview set, usability test, show-and-tell, synthesis deck or research report.
+
+```text
+# Research ingestion draft
+
+## Import classification
+
+Type: research
+Recommended inbox: hippocampus/inbox/research/
+Fit: good | needs review | poor
+
+## Source material
+
+Source:
+SharePoint link:
+Date:
+Author or team:
+Pages or slides reviewed:
+
+## Research round
+
+Title:
+Date:
+Summary:
+
+## Participants
+
+Participant: [label] - [role or user group]
+Participant: [label] - [role or user group]
+
+## Findings and insights
+
+Insight: [short evidence-backed insight]
+Summary: [what was observed, by whom, and why it matters]
+Evidence: [source document, page/slide/section]
+Confidence: high | medium | low
+
+Insight: [short evidence-backed insight]
+Summary: [what was observed, by whom, and why it matters]
+Evidence: [source document, page/slide/section]
+Confidence: high | medium | low
+
+## Design actions
+
+Action: [specific design or content action]
+Rationale: [which insight or evidence supports it]
+Status: proposed
+
+Action: [specific design or content action]
+Rationale: [which insight or evidence supports it]
+Status: proposed
+
+## Suggested graph links
+
+Existing entity:
+Relationship:
+New entity:
+Evidence:
+
+## Assumptions or gaps
+
+- [Anything uncertain, missing or requiring human review]
+```
+
+## Project Context Output Template
+
+Use this when the source material is a project overview, mapping board, policy summary, proposition deck, service map or general briefing.
+
+```text
+# Project context ingestion draft
+
+## Import classification
+
+Type: project context
+Recommended inbox: hippocampus/inbox/project/
+Fit: good | needs review | poor
+
+## Source material
+
+Source:
+SharePoint link:
+Date:
+Author or team:
+Pages or slides reviewed:
+
+## Overview
+
+Purpose:
+Vision:
+Problem statement:
+Service proposition:
+
+## Users
+
+User: [user group]
+Group: external | internal | data consumer | other
+Description:
+
+User: [user group]
+Group: external | internal | data consumer | other
+Description:
+
+## Channels
+
+Channel: [channel name]
+Usage:
+Description:
+
+Channel: [channel name]
+Usage:
+Description:
+
+## Policies and regulations
+
+Policy: [policy or regulation name]
+Summary:
+Source:
+
+## Constraints
+
+Constraint: [constraint]
+Detail:
+Impact:
+
+## Risks
+
+Risk: [risk]
+Detail:
+Severity: high | medium | low
+
+## Milestones
+
+Milestone: [milestone]
+Date:
+Detail:
+
+## Facts
+
+Fact: [fact label]
+Value:
+Detail:
+Source:
+
+## Assumptions or gaps
+
+- [Anything uncertain, missing or requiring human review]
+```
+
+## Ingestion Readiness Check
+
+Before the agent says a document is ready, it must check:
+
+- The document has a clear classification: research or project context.
+- Every important claim has a source reference.
+- Research material includes findings or insights, not just raw notes.
+- Design actions are linked to evidence or insights.
+- Project context does not include invented strategy or unverified policy detail.
+- Duplicates and contradictions are called out.
+- Sensitive material is not copied unnecessarily.
+- The output uses stable headings and UK spelling.
+
+## Recommended Workflow
+
+1. Ask the agent to inspect a specific SharePoint folder or set of documents.
+2. Ask it to classify the material as research, project context or mixed.
+3. Ask it to produce one ingestion draft per coherent artefact or theme.
+4. Export the draft as a document or PDF.
+5. Put the exported document into the matching Hippocampus inbox:
+
+   ```text
+   hippocampus/inbox/research/
+   hippocampus/inbox/project/
+   ```
+
+6. Run the matching sync command:
+
+   ```bash
+   npx hippocampus research sync -- --no-promote
+   npx hippocampus import project-context -- --no-promote
+   ```
+
+7. Review the generated `.review.md` and `.json` files.
+8. Promote only after review.
+
+## Guardrails
+
+The agent must not:
+
+- treat SharePoint search results as evidence without opening the source
+- invent dates, participants, roles or decisions
+- collapse conflicting findings into a false consensus
+- expose confidential or sensitive material outside the approved workspace
+- create final Hippocampus source data without review
+- use US spelling for artefacts
+
+## Good First Pilot
+
+Start with a narrow SharePoint folder and one question:
+
+```text
+Review the NCRS research material in this folder and produce one Hippocampus research ingestion draft for the strongest repeated findings about [user group or journey].
+```
+
+Then test:
+
+- whether the sources are cited well enough
+- whether the output fits `research:sync`
+- whether a designer or researcher can review it quickly
+- whether the agent separates evidence from assumptions