@hippo-digital/hippocampus 1.0.0-rc.2 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -49,7 +49,21 @@ journeys and screens they justify, rendered as a viewer inside your prototype.
 
 - The 13 guides are served at `{basePath}/docs`, version-matched to the
   installed package rather than copied into your repo.
-- `skills install` copies the 20 agent skills into `.github/skills` with content
-  hashes, so an upgrade can tell a stale copy from one your team has edited.
+- `skills install` copies the 21 skills into `.github/skills`, the six agents
+  into `.github/agents` and the instructions into `.github/instructions`, with
+  content hashes so an upgrade can tell a stale copy from one your team has
+  edited. They install together because every agent's preferred skills point
+  into `.github/skills` and every skill names its `owners` by agent, so either
+  half alone is a set of dangling references. `--no-agents` installs the skills
+  only.
+- Everything the agents and skills reference that is not a repo file is read
+  from the installed package, so those references are version-matched too.
+- `skills validate` checks both directions between skills and agents: a skill
+  owned by an agent that does not exist, an agent naming a skill that is not in
+  the catalog, and a skill in the catalog that no agent lists - the last of
+  which was true of four skills, installed but invisible to the runtime.
+- `init` scaffolds `artefacts/` with the READMEs carrying the naming
+  conventions, so the skills writing accessibility notes, screenshot review
+  packs and delivery summaries have somewhere to put them in a fresh host.
 - `init` reports research material in `hippocampus/source-artefacts/` rather
   than silently committing it; `--private-artefacts` gitignores it.

package/README.md

@@ -34,11 +34,18 @@ back out and leaves every byte of your knowledge base where it is.
 
 ```bash
 npx hippocampus doctor        # what is wired, what is not, and where it looked
-npx hippocampus skills install  # copy the agent skills into .github/skills
+npx hippocampus skills install  # copy the skills, agents and instructions in
 ```
 
-`skills install` records a hash of what it wrote, so a later upgrade can tell a
-stale copy from one your team has edited - the edited one is left alone.
+`skills install` writes three directories: `.github/skills` (the skill catalog),
+`.github/agents` (role wrappers naming who runs each skill) and
+`.github/instructions`. They install together because every agent's preferred
+skills point into `.github/skills`, and every skill names its `owners` by agent,
+so either half on its own is a set of dangling references. `--no-agents`
+installs the skills alone for a host whose agent runtime is not Copilot.
+
+It records a hash of what it wrote, so a later upgrade can tell a stale copy
+from one your team has edited - the edited one is left alone and named.
 
 ## Wiring it by hand
 
@@ -119,9 +126,11 @@ describe the version you have installed. Nothing is copied into your repo -
 a copied guide goes stale within a release, and the stale one is the copy people
 read, because it is the one sitting in their editor.
 
-`skills install` is the deliberate exception: an agent reads skills as repo
-files, so those are copied, with hashes so an upgrade can tell a stale copy from
-one your team has edited.
+`skills install` is the deliberate exception: an agent reads skills, agent
+definitions and instructions as repo files, so those are copied, with hashes so
+an upgrade can tell a stale copy from one your team has edited. Everything they
+reference that is not a repo file is read from the installed package, so those
+references cannot go stale either.
 
 ## Keeping research material out of the repo
 

package/agents/README.md

@@ -0,0 +1,32 @@
+# Agents
+
+These agent definitions are Copilot-friendly role wrappers for the portable skill catalog in `.github/skills/`.
+
+Use role agents to decide **who** should do the work. Use skill files to decide **how** the task should be run with repo docs, scripts and finish checks.
+
+Use the source model as the handoff contract between agents.
+
+## Agents
+
+- `knowledge-builder.md`
+- `prototype-builder.md`
+- `ingestion-curator.md`
+- `screenshot-runner.md`
+- `accessibility-tester.md`
+- `workflow-orchestrator.md`
+
+## Portable skills
+
+- See `.github/skills/README.md` for the catalog.
+- See `.github/skills/skills.json` for a machine-readable index that other agent runtimes can parse.
+- See `.github/skills/COVERAGE-MATRIX.md` for archived prompt to current skill mapping.
+
+## Common entrypoints
+
+- End-to-end research ingestion: `.github/skills/ingest-research-round.skill.md`
+- End-to-end project context ingestion: `.github/skills/ingest-project-context.skill.md`
+- End-to-end service slice delivery: `.github/skills/deliver-service-slice.skill.md`
+- Route review pack: `.github/skills/capture-route-review-pack.skill.md`
+- Accessibility review note: `.github/skills/record-accessibility-review.skill.md`
+- Route review handover: `.github/skills/write-route-review-summary.skill.md`
+

package/agents/accessibility-tester.md

@@ -0,0 +1,21 @@
+# accessibility-tester
+
+Reviews accessibility of changed prototype and Hippocampus pages.
+
+## Responsibilities
+
+- Check heading order, labels, link text and keyboard flow.
+- Check NHS component usage.
+- Store findings under `artefacts/accessibility/`.
+- Separate blockers from improvements.
+
+## Preferred Skills
+
+- `.github/skills/record-accessibility-review.skill.md`
+- `.github/skills/write-route-review-summary.skill.md`
+
+## Read First
+
+- `.github/instructions/nhs-frontend.instructions.md`
+- `node_modules/@hippo-digital/hippocampus/docs/custom-agents-usage.md`
+- `artefacts/accessibility/README.md`

package/agents/ingestion-curator.md

@@ -0,0 +1,29 @@
+# ingestion-curator
+
+Improves script-generated research and project-context drafts before human review and promotion.
+
+## Responsibilities
+
+- Work in `hippocampus/imports/research/` and `hippocampus/imports/project/`.
+- Combine extracted draft files with source-model docs and promotion scripts.
+- Keep reviewable metadata and extracted text intact.
+- Run dry-run promotion checks, not direct promotion.
+- Summarise changed draft fields, evidence gaps and remaining warnings.
+
+## Preferred Skills
+
+- `.github/skills/ingest-project-context.skill.md`
+- `.github/skills/ingest-research-round.skill.md`
+- `.github/skills/structure-project-context-draft.skill.md`
+- `.github/skills/structure-research-draft.skill.md`
+- `.github/skills/review-research-import-draft.skill.md`
+- `.github/skills/map-research-to-graph.skill.md`
+- `.github/skills/ingest-user-personas.skill.md`
+- `.github/skills/record-design-decision.skill.md`
+- `.github/skills/triage-research-corpus.skill.md`
+
+## Read First
+
+- `node_modules/@hippo-digital/hippocampus/docs/repeatable-research-round-ingestion.md`
+- `.github/instructions/knowledge-source.instructions.md`
+

package/agents/knowledge-builder.md

@@ -0,0 +1,29 @@
+# knowledge-builder
+
+Maintains the Hippocampus source model.
+
+## Responsibilities
+
+- Edit `hippocampus/source`.
+- Preserve linked source relationships.
+- Add assumptions when evidence is missing.
+- Run `npx hippocampus validate`.
+- Summarise records changed and unresolved assumptions.
+
+## Preferred Skills
+
+- `.github/skills/deliver-service-slice.skill.md`
+- `.github/skills/generate-service-slice.skill.md`
+- `.github/skills/add-user-needs.skill.md`
+- `.github/skills/add-scenario.skill.md`
+- `.github/skills/create-journey-from-scenario.skill.md`
+- `.github/skills/audit-knowledge-source.skill.md`
+- `.github/skills/ingest-user-personas.skill.md`
+- `.github/skills/record-design-decision.skill.md`
+- `.github/skills/onboard-team-member.skill.md`
+
+## Read First
+
+- `node_modules/@hippo-digital/hippocampus/docs/source-model.md`
+- `.github/instructions/knowledge-source.instructions.md`
+- `node_modules/@hippo-digital/hippocampus/lib/schema.js`

package/agents/prototype-builder.md

@@ -0,0 +1,23 @@
+# prototype-builder
+
+Builds NHS Prototype Kit routes and views from the source model.
+
+## Responsibilities
+
+- Edit `app/routes.js` and `app/views`.
+- Use source data rather than hard-coded service facts.
+- Reuse Hippocampus components where practical.
+- Keep NHS UK Frontend conventions.
+- Run `npx hippocampus validate` and `npx hippocampus doctor` when routes, views or screen routes change.
+
+## Preferred Skills
+
+- `.github/skills/deliver-service-slice.skill.md`
+- `.github/skills/add-prototype-screen.skill.md`
+- `.github/skills/audit-knowledge-source.skill.md`
+
+## Read First
+
+- `.github/instructions/nhs-prototype-kit.instructions.md`
+- `.github/instructions/nhs-frontend.instructions.md`
+- `app/routes.js`

package/agents/screenshot-runner.md

@@ -0,0 +1,22 @@
+# screenshot-runner
+
+Captures review evidence for prototype and Hippocampus routes.
+
+## Responsibilities
+
+- Start the prototype kit when needed.
+- Visit changed routes.
+- Capture screenshots or concise route notes.
+- Store outputs under `artefacts/screenshots/<YYYY-MM-DD>-<topic>/`.
+- Write a manifest describing routes captured and issues found.
+
+## Preferred Skills
+
+- `.github/skills/capture-route-review-pack.skill.md`
+- `.github/skills/write-route-review-summary.skill.md`
+
+## Read First
+
+- `node_modules/@hippo-digital/hippocampus/docs/custom-agents-usage.md`
+- `artefacts/screenshots/README.md`
+- `app/routes.js`

package/agents/workflow-orchestrator.md

@@ -0,0 +1,37 @@
+# workflow-orchestrator
+
+Coordinates larger Hippocampus delivery work.
+
+## Responsibilities
+
+- Break work into source, prototype, validation and review steps.
+- Use `knowledge-builder` before `prototype-builder` for service content.
+- Use `ingestion-curator` for script-generated research and project-context drafts.
+- Request screenshot and accessibility review for visible journeys.
+- Store delivery summaries under `artefacts/delivery-summaries/`.
+
+## Preferred Skills
+
+- `.github/skills/deliver-service-slice.skill.md`
+- `.github/skills/ingest-project-context.skill.md`
+- `.github/skills/ingest-research-round.skill.md`
+- `.github/skills/write-delivery-summary.skill.md`
+- `.github/skills/capture-route-review-pack.skill.md`
+- `.github/skills/record-accessibility-review.skill.md`
+- `.github/skills/write-route-review-summary.skill.md`
+- `.github/skills/generate-service-slice.skill.md`
+- `.github/skills/add-prototype-screen.skill.md`
+- `.github/skills/structure-project-context-draft.skill.md`
+- `.github/skills/structure-research-draft.skill.md`
+- `.github/skills/review-research-import-draft.skill.md`
+- `.github/skills/map-research-to-graph.skill.md`
+- `.github/skills/audit-knowledge-source.skill.md`
+- `.github/skills/triage-research-corpus.skill.md`
+- `.github/skills/onboard-team-member.skill.md`
+
+## Required Finish
+
+- Validation result.
+- Routes or artefacts reviewed.
+- Assumptions and unresolved risks.
+- Suggested next action.

package/bin/hippocampus.js

@@ -24,7 +24,7 @@ const COMMANDS = {
   'link insight-needs': 'link-insights-to-needs.js',
   'source index': 'index-source-artefacts.js',
   'source audit': 'audit-provenance.js',
-  'skills install': 'install-skills.js',
+  'skills install': 'install-skills.js', // also installs agents and instructions
   'skills validate': 'validate-skills.js'
 }
 
@@ -37,6 +37,7 @@ function usage () {
   for (const name of Object.keys(COMMANDS)) console.log(`  ${name}`)
   console.log('\nOptions:')
   console.log('  --root <dir>   the project to act on (default: nearest project above the cwd)')
+  console.log('  --no-agents    skills install: skills only, no agents or instructions')
   console.log('  --version      print the installed version')
   console.log('  --help         this message')
   console.log('\nEvery command resolves a project root the same way; run `hippocampus validate`')

package/instructions/knowledge-source.instructions.md

@@ -0,0 +1,29 @@
+---
+applyTo: "hippocampus/source/**/*.json,app/lib/hippocampus/**/*.js,scripts/validate-knowledge.js,docs/source-model.md"
+---
+
+# Knowledge Source Instructions
+
+The Hippocampus knowledge base is source-model first. JSON records in `hippocampus/source` drive the visible artefacts and prototype traceability.
+
+## Editing Rules
+
+- Read `docs/source-model.md` before editing records.
+- Use structured JSON edits. Do not rely on fragile string manipulation.
+- Keep IDs lowercase kebab-case.
+- Preserve IDs unless a rename is explicitly requested.
+- Keep arrays ordered for human review: project context first, then journey/user-facing order.
+- Add assumptions instead of unsupported evidence claims.
+- Use fictional and synthetic content only.
+
+## Required Checks
+
+Run:
+
+```bash
+npm run validate:knowledge
+```
+
+Validation must pass before the work is considered done.
+
+If validation fails, fix the source relationships or schema issue before changing views.

package/instructions/nhs-frontend.instructions.md

@@ -0,0 +1,22 @@
+---
+applyTo: "app/views/**/*.html,app/views/**/*.njk,app/assets/sass/**/*.scss"
+---
+
+# NHS Frontend Instructions
+
+Use NHS UK Frontend conventions.
+
+## Interface Rules
+
+- Use NHS component classes before custom styling.
+- Keep headings hierarchical and page-specific.
+- Use summary lists, cards, tables and tags only when they improve scanning.
+- Use clear link text that makes sense out of context.
+- Keep prototype screens accessible and keyboard-friendly.
+- Avoid decorative UI that does not help the service-design task.
+
+## Content Rules
+
+- Write plain, task-focused NHS-style content.
+- Keep clinical and service details synthetic unless explicitly provided as approved source material.
+- Avoid overclaiming certainty. Represent unknowns as assumptions or risks.

package/instructions/nhs-prototype-kit.instructions.md

@@ -0,0 +1,30 @@
+---
+applyTo: "app/routes.js,app/views/**/*.html,app/views/**/*.njk,app/config.js"
+---
+
+# NHS Prototype Kit Instructions
+
+Use the existing NHS Prototype Kit structure.
+
+## Routes
+
+- Keep route handlers in `app/routes.js` concise.
+- Load knowledge through `app/lib/hippocampus/load-knowledge.js`.
+- Return useful not-found states instead of crashing on missing IDs.
+
+## Views
+
+- Use Nunjucks and NHS UK Frontend classes.
+- Reuse components from `app/views/hippocampus/components` when patterns repeat.
+- Keep page content driven by source data wherever possible.
+- Do not put service facts only in Nunjucks if they belong in `hippocampus/source`.
+
+## Checks
+
+After route or view changes, run:
+
+```bash
+npm run validate:knowledge
+```
+
+When practical, start the kit and smoke-test affected routes.

package/lib/package-paths.js

@@ -28,5 +28,7 @@ module.exports = {
   scriptsDir: path.join(packageRoot, 'scripts'),
   templatesDir: path.join(packageRoot, 'templates'),
   skillsDir: path.join(packageRoot, 'skills'),
+  agentsDir: path.join(packageRoot, 'agents'),
+  instructionsDir: path.join(packageRoot, 'instructions'),
   docsDir: path.join(packageRoot, 'docs')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hippo-digital/hippocampus",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.3",
   "description": "A design-knowledge base for NHS Prototype Kit projects: research, insights, needs, journeys and screens, traceable end to end.",
   "license": "MIT",
   "main": "index.js",
@@ -15,6 +15,8 @@
     "assets",
     "scripts",
     "skills",
+    "agents",
+    "instructions",
     "templates",
     "docs",
     "README.md",

package/scripts/init.js

@@ -4,6 +4,7 @@ const path = require('path')
 const { resolveRoot, CONFIG_FILENAME } = require('../lib/resolve-root')
 const { CURRENT_SCHEMA_VERSION } = require('../lib/schema-version')
 const hostEdit = require('../lib/host-edit')
+const packagePaths = require('../lib/package-paths')
 
 // Set a host project up to use Hippocampus: write the config and an empty
 // knowledge base, then make the two host edits - both inside marked blocks, both
@@ -37,6 +38,7 @@ function main () {
 
   planConfig(root)
   planKnowledgeBase(root)
+  planArtefacts(root, artefactsDir(root))
   planArtefactGovernance(root)
   if (!noWire) {
     planHostEdit(path.join(root, 'app/routes.js'), wireRoutes)
@@ -75,6 +77,54 @@ function planConfig (root) {
   }, null, 2) + '\n'))
 }
 
+// Several skills write into `artefacts/` - accessibility notes, screenshot
+// review packs, delivery summaries - and two agents name the READMEs there as
+// required reading. A fresh host had none of it, so those skills had nowhere to
+// put their output and the agents pointed at files that did not exist. The
+// READMEs carry the naming conventions, which is the part that stops every
+// project inventing its own.
+//
+// Each file is written only when absent: these are the host's to edit.
+// The host may have renamed it in the config; honour that rather than assuming.
+function artefactsDir (root) {
+  const configPath = path.join(root, CONFIG_FILENAME)
+  if (!fs.existsSync(configPath)) return 'artefacts'
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8')).artefactsDir || 'artefacts'
+  } catch {
+    return 'artefacts'
+  }
+}
+
+function planArtefacts (root, artefactsDir) {
+  const from = path.join(packagePaths.templatesDir, 'artefacts')
+  const to = path.join(root, artefactsDir)
+  const missing = []
+
+  for (const rel of listTemplateFiles(from)) {
+    if (!fs.existsSync(path.join(to, rel))) missing.push(rel)
+  }
+  if (!missing.length) return
+
+  plan(`${artefactsDir}/ and ${missing.length} README${missing.length === 1 ? '' : 's'}`, () => {
+    for (const rel of missing) {
+      const target = path.join(to, rel)
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.copyFileSync(path.join(from, rel), target)
+    }
+  })
+}
+
+function listTemplateFiles (dir, prefix = '') {
+  const found = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? path.posix.join(prefix, entry.name) : entry.name
+    if (entry.isDirectory()) found.push(...listTemplateFiles(path.join(dir, entry.name), rel))
+    else found.push(rel)
+  }
+  return found
+}
+
 function planKnowledgeBase (root) {
   const sourceDir = path.join(root, 'hippocampus/source')
   const projectPath = path.join(sourceDir, 'project.json')

package/scripts/install-skills.js

@@ -17,50 +17,121 @@ const packagePaths = require('../lib/package-paths')
 //
 // Shared files a host is entitled to own - the README, the format contract, the
 // schema - are written only when absent.
+//
+// Agents and instructions install alongside skills rather than under a command
+// of their own. Every agent's "Preferred Skills" list points into
+// `.github/skills/`, so an agent installed without its skills is a file full of
+// dangling links, and a skill catalog with no agents has nothing naming who runs
+// what - all 21 skills declare `owners`. Installing them together is the only
+// combination that leaves the host consistent. `--no-agents` opts out for a host
+// whose agent runtime is not Copilot; the skills still install.
 
 const argv = process.argv.slice(2)
 const dryRun = argv.includes('--dry-run')
 const force = argv.includes('--force')
+const withAgents = !argv.includes('--no-agents')
 const MANIFEST = '.hippocampus-skills.json'
 const NEVER_OVERWRITE = new Set(['README.md', 'SKILL-FORMAT.md', 'skills.schema.json', 'COVERAGE-MATRIX.md'])
 
+// The manifest records a hash per installed file. Skills and agents both ship a
+// README.md, so the three trees get their own maps rather than one flat one -
+// a single map would have the agents' README silently claim the skills' hash and
+// then report both as locally edited on the next upgrade.
+const TREES = [
+  { key: 'files', source: 'skillsDir', target: '.github/skills', label: 'skills' },
+  { key: 'agents', source: 'agentsDir', target: '.github/agents', label: 'agents' },
+  { key: 'instructions', source: 'instructionsDir', target: '.github/instructions', label: 'instructions' }
+]
+
 function hash (text) {
   return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16)
 }
 
 function main () {
   const { root } = resolveRoot({ argv })
-  const targetDir = path.join(root, '.github/skills')
-  const manifestPath = path.join(targetDir, MANIFEST)
+  const skillsTarget = path.join(root, '.github/skills')
+  const manifestPath = path.join(skillsTarget, MANIFEST)
   const manifest = fs.existsSync(manifestPath)
     ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
-    : { files: {}, skillIds: [] }
-  manifest.files = manifest.files || {}
+    : {}
   manifest.skillIds = manifest.skillIds || []
 
-  console.log(`Project root: ${root}`)
-  console.log(`Installing to: ${path.relative(root, targetDir)}\n`)
+  console.log(`Project root: ${root}\n`)
+
+  const trees = TREES.filter((tree) => tree.key === 'files' || withAgents)
+  let wroteAnything = false
+  let anySkipped = false
+
+  for (const tree of trees) {
+    manifest[tree.key] = manifest[tree.key] || {}
+    const sourceDir = packagePaths[tree.source]
+    if (!fs.existsSync(sourceDir)) continue
 
+    const result = installTree(sourceDir, path.join(root, tree.target), manifest[tree.key])
+    wroteAnything = wroteAnything || result.written.length > 0
+    anySkipped = anySkipped || result.skipped.length > 0
+
+    console.log(`${tree.target}`)
+    console.log(`  ${dryRun ? 'would install' : 'installed'}: ${result.written.length} files`)
+    if (result.unchanged.length) console.log(`  already current: ${result.unchanged.length}`)
+    if (result.kept.length) console.log(`  left as yours: ${result.kept.join(', ')}`)
+    if (result.skipped.length) {
+      console.log(`  left alone because they have been edited here (${result.skipped.length}):`)
+      for (const name of result.skipped) console.log(`    ${name}`)
+    }
+
+    if (tree.key === 'files') {
+      const merged = mergeCatalog(skillsTarget, manifest)
+      wroteAnything = wroteAnything || merged.added.length > 0
+      console.log(`  ${dryRun ? 'would add' : 'added'} to the catalog: ${merged.added.length} skills` +
+        (merged.existing ? ` (alongside ${merged.existing} already there)` : ''))
+      if (merged.refreshed) console.log(`  refreshed in the catalog: ${merged.refreshed} entries`)
+    }
+    console.log('')
+  }
+
+  if (!withAgents) {
+    console.log('Agents and instructions were not installed (--no-agents).')
+    console.log('Skills declare owners by agent name, so without them nothing names who runs each skill.\n')
+  }
+
+  if (anySkipped) {
+    console.log('Re-install edited files with --force once you have kept whatever you changed.\n')
+  }
+
+  if (!dryRun && wroteAnything) {
+    manifest.version = require('../package.json').version
+    manifest.updatedAt = new Date().toISOString()
+    fs.mkdirSync(skillsTarget, { recursive: true })
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+  }
+}
+
+/**
+ * Copy one tree of package-owned files into the host, recording a hash of each
+ * so a later upgrade can tell "we wrote this and it is untouched" from "someone
+ * has edited it here". Untouched files are refreshed silently; edited ones are
+ * named and left alone unless --force.
+ */
+function installTree (sourceDir, targetDir, manifestFiles) {
   const written = []
   const skipped = []
   const unchanged = []
   const kept = []
 
-  for (const name of fs.readdirSync(packagePaths.skillsDir)) {
+  for (const name of fs.readdirSync(sourceDir)) {
     if (name === 'skills.json' || !/\.(skill\.md|md|json)$/.test(name)) continue
 
     const to = path.join(targetDir, name)
-    const content = fs.readFileSync(path.join(packagePaths.skillsDir, name), 'utf8')
+    const content = fs.readFileSync(path.join(sourceDir, name), 'utf8')
     const incoming = hash(content)
 
     if (fs.existsSync(to)) {
       const current = hash(fs.readFileSync(to, 'utf8'))
       if (current === incoming) { unchanged.push(name); continue }
       if (NEVER_OVERWRITE.has(name)) { kept.push(name); continue }
-      const installed = manifest.files[name]
+      const installed = manifestFiles[name]
       if (installed && current !== installed && !force) { skipped.push(name); continue }
-    } else if (NEVER_OVERWRITE.has(name) && name !== 'SKILL-FORMAT.md' && name !== 'skills.schema.json') {
-      // A README the host does not have is worth providing; one it does is not.
     }
 
     written.push(name)
@@ -68,29 +139,10 @@ function main () {
       fs.mkdirSync(targetDir, { recursive: true })
       fs.writeFileSync(to, content)
     }
-    manifest.files[name] = incoming
+    manifestFiles[name] = incoming
   }
 
-  const merged = mergeCatalog(targetDir, manifest)
-
-  if (!dryRun && (written.length || merged.added.length)) {
-    manifest.version = require('../package.json').version
-    manifest.updatedAt = new Date().toISOString()
-    fs.mkdirSync(targetDir, { recursive: true })
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
-  }
-
-  console.log(`${dryRun ? 'would install' : 'installed'}: ${written.length} files`)
-  console.log(`${dryRun ? 'would add' : 'added'} to the catalog: ${merged.added.length} skills` +
-    (merged.existing ? ` (alongside ${merged.existing} already there)` : ''))
-  if (merged.refreshed) console.log(`refreshed in the catalog: ${merged.refreshed} entries`)
-  if (unchanged.length) console.log(`already current: ${unchanged.length}`)
-  if (kept.length) console.log(`left as yours: ${kept.join(', ')}`)
-  if (skipped.length) {
-    console.log(`\nleft alone because they have been edited here (${skipped.length}):`)
-    for (const name of skipped) console.log(`  ${name}`)
-    console.log('\nRe-install them with --force once you have kept whatever you changed.')
-  }
+  return { written, skipped, unchanged, kept }
 }
 
 /**

package/scripts/validate-skills.js

@@ -103,6 +103,8 @@ function main () {
     validateSkillFile(skillPath, entry, catalogIds, errors)
   }
 
+  validateAgents(catalog, errors)
+
   if (errors.length) {
     console.error('Skill catalog is invalid')
     for (const error of errors) {
@@ -114,6 +116,49 @@ function main () {
   console.log(`Skill catalog is valid (${catalog.skills.length} skills)`)
 }
 
+/**
+ * Agents and skills point at each other and nothing was checking either
+ * direction. Both halves rot the same way and both are silent:
+ *
+ *   - a skill names an `owners` agent that does not exist, so nobody runs it;
+ *   - an agent lists a Preferred Skill that has been renamed or removed, so the
+ *     agent opens a file that is not there;
+ *   - a skill exists, declares owners, and no agent lists it - which is how four
+ *     skills ended up installed but invisible to the runtime.
+ *
+ * The third is the one worth having a test for, because the skill looks fine
+ * from every angle except the only one that matters.
+ */
+function validateAgents (catalog, errors) {
+  const agentsDir = packagePaths.agentsDir
+  if (!fs.existsSync(agentsDir)) return
+
+  const agentFiles = fs.readdirSync(agentsDir).filter((name) => name.endsWith('.md'))
+  const agentNames = new Set(agentFiles.filter((name) => name !== 'README.md').map((name) => name.replace(/\.md$/, '')))
+
+  const referenced = new Set()
+  for (const name of agentFiles) {
+    const text = fs.readFileSync(path.join(agentsDir, name), 'utf8')
+    for (const match of text.matchAll(/\.github\/skills\/([a-z0-9-]+\.skill\.md)/g)) {
+      referenced.add(match[1])
+      if (!catalog.skills.some((skill) => skill.file === match[1])) {
+        errors.push(`agents/${name} names a skill that is not in the catalog: ${match[1]}`)
+      }
+    }
+  }
+
+  for (const skill of catalog.skills) {
+    for (const owner of skill.owners) {
+      if (!agentNames.has(owner)) {
+        errors.push(`${skill.file} is owned by an agent that does not exist: ${owner}`)
+      }
+    }
+    if (!referenced.has(skill.file)) {
+      errors.push(`${skill.file} is in the catalog but no agent lists it, so no agent will find it`)
+    }
+  }
+}
+
 function validateSkillFile (skillPath, catalogEntry, catalogIds, errors) {
   let parsed
 

package/skills/add-prototype-screen.skill.md

@@ -6,7 +6,6 @@ owners:
   - prototype-builder
   - workflow-orchestrator
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/screens.json
   - hippocampus/source/needs.json

package/skills/add-scenario.skill.md

@@ -6,7 +6,6 @@ owners:
   - knowledge-builder
   - workflow-orchestrator
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/users.json
   - hippocampus/source/needs.json

package/skills/add-user-needs.skill.md

@@ -6,7 +6,6 @@ owners:
   - knowledge-builder
   - workflow-orchestrator
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/users.json
   - hippocampus/source/needs.json

package/skills/audit-knowledge-source.skill.md

@@ -6,7 +6,6 @@ owners:
   - knowledge-builder
   - workflow-orchestrator
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/
   - app/routes.js

package/skills/create-journey-from-scenario.skill.md

@@ -6,7 +6,6 @@ owners:
   - knowledge-builder
   - workflow-orchestrator
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/scenarios.json
   - hippocampus/source/journeys.json

package/skills/deliver-service-slice.skill.md

@@ -16,7 +16,6 @@ composes:
 reads:
   - node_modules/@hippo-digital/hippocampus/docs/agent-workflow.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - app/routes.js
   - hippocampus/source/
   - app/views/

package/skills/generate-service-slice.skill.md

@@ -6,7 +6,6 @@ owners:
   - knowledge-builder
   - workflow-orchestrator
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/
 edits:

package/skills/ingest-project-context.skill.md

@@ -11,7 +11,6 @@ reads:
   - node_modules/@hippo-digital/hippocampus/docs/repeatable-research-round-ingestion.md
   - node_modules/@hippo-digital/hippocampus/docs/hippocampus-technical.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/inbox/project/
   - hippocampus/imports/project/[draft-id].review.md
   - hippocampus/imports/project/[draft-id].json

package/skills/ingest-user-personas.skill.md

@@ -13,6 +13,7 @@ reads:
   - hippocampus/source/needs.json
   - hippocampus/source/evidence.json
   - hippocampus/source/assumptions.json
+  - hippocampus/source/relationships.json
 edits:
   - hippocampus/source/users.json
   - hippocampus/source/needs.json

package/skills/map-research-to-graph.skill.md

@@ -9,7 +9,6 @@ owners:
 reads:
   - node_modules/@hippo-digital/hippocampus/docs/research-knowledge-graph.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/source/users.json
   - hippocampus/source/needs.json
   - hippocampus/source/scenarios.json

package/skills/onboard-team-member.skill.md

@@ -0,0 +1,109 @@
+---
+id: onboard-team-member
+title: Onboard a team member
+purpose: Orient someone new to the project from what the knowledge base already knows, and leave them a dated briefing they can read without an agent.
+owners:
+  - knowledge-builder
+  - workflow-orchestrator
+composes:
+  - ingest-project-context
+  - audit-knowledge-source
+reads:
+  - hippocampus/source/project.json
+  - hippocampus/source/project-context.json
+  - hippocampus/source/users.json
+  - hippocampus/source/needs.json
+  - hippocampus/source/insights.json
+  - hippocampus/source/design-actions.json
+  - hippocampus/source/decisions.json
+  - hippocampus/source/screens.json
+  - hippocampus/source/research-rounds.json
+  - hippocampus/source/relationships.json
+edits:
+  - artefacts/onboarding/
+runs:
+  - npx hippocampus validate
+outputs:
+  - Answers to a new joiner's questions, grounded in the knowledge base
+  - A dated briefing under artefacts/onboarding/ when one is asked for
+guardrails:
+  - Separate what was counted from what was written. State every figure as of today's date and name the file each narrative claim came from.
+  - Do not invent the project narrative. If project-context.json is empty, say so and point at ingest-project-context rather than describing the project from the graph alone.
+  - Write for content, service and interaction designers and user researchers. No file paths, schema names or CLI commands in the briefing itself - link to viewer pages instead.
+  - Do not present coverage gaps as failures. "Most needs have no screen" is normal on a project where one slice has been designed; say which slice, not just the number.
+  - A project with no rounds, insights or actions is new, not failing. Say so, drop the empty sections, and write a starting guide instead of a status report.
+  - The briefing must stand alone. Someone with no agent and no terminal should be able to read it and know where to go next.
+acceptance:
+  - Every figure in the output is derived from the knowledge base, not recalled.
+  - Narrative claims are attributed, or their absence is stated.
+  - Each named role has something specific to do next.
+  - A briefing, if produced, is dated and readable without an agent.
+  - npx hippocampus validate passes.
+---
+
+# Onboard a team member
+
+## Use when
+- Someone joins a project that already has a knowledge base and needs to know what is known, what is decided, and what is open.
+- Someone is picking up work after a handover and wants the current state rather than the history.
+
+Works in two modes. **Live** - answer their questions in conversation, grounded in the records. **Briefing** - write a dated document to `artefacts/onboarding/` for someone who does not have an agent set up yet, or who wants something to keep.
+
+## Workflow
+
+### Read these first
+
+1. `project.json` and `project-context.json` for what the project is. **`project-context.json` is the narrative half.** If its `purpose`, `problemStatement` and `constraints` are empty, the project has never recorded why it exists - say that plainly and suggest `ingest-project-context`. Do not reconstruct a purpose from the graph.
+2. The graph for the state. Everything below is counted, not remembered.
+3. `npx hippocampus validate` for the coverage notes.
+
+### Compute rather than recall
+
+| Question a joiner asks | Where the answer comes from |
+| --- | --- |
+| What have we learned? | insights, grouped by research round, with participant counts |
+| Who are we designing for? | users, and how many needs each carries |
+| What has been designed? | screens, and which needs they address |
+| What is still open? | design actions by status |
+| What has been decided? | decisions by status; flag any whose consequence is unrecorded |
+| Where are the gaps? | needs with no screen, insights with no need, rounds with no insights |
+
+Give the figure and the reading of it. "108 of 132 needs have no screen" is data; "only patient search has been designed, so most needs are untouched - that is the backlog, not a fault" is orientation.
+
+### When the knowledge base is thin
+
+A new project has few records, and a briefing full of zeros reads as though something is
+broken. Check before writing: a project with no research rounds, no insights and no design
+actions is **new, not failing**, and the briefing should say so in its first line and become
+a starting guide rather than a status report.
+
+In that case, skip the research and open-work sections entirely - an empty section invites
+the reader to think something is missing - and tell them what the project does have and what
+the first records should be. A project with screens and needs but no research has been
+designed on assumptions; that is worth naming, because it is exactly the thing a new
+researcher is there to fix.
+
+Only report a count as a gap when there is enough around it for the gap to mean something.
+
+### By role
+
+Give each person one specific thing to look at and one they could do this week.
+
+- **User researcher** - which rounds produced insights and which did not, insights not yet linked to a need, and whether participants are recorded for each round. The unlinked insights are usually the most useful first contribution.
+- **Content designer** - the screens that exist and the needs behind them. Words on a screen trace back to a need statement written in a user's own language; that is where to check whether the two still agree.
+- **Service designer** - the journeys and their blueprint lanes, and which lanes are empty. An empty backstage or governance lane is a question nobody has answered yet.
+- **Interaction / UX designer** - needs with no screen, and design actions still `proposed`. Those two lists together are the design backlog.
+
+## Guardrails
+
+- Separate what was counted from what was written. State figures as of today's date; name the file each narrative claim came from.
+- Do not invent the project narrative.
+- No file paths, schema names or CLI commands in the briefing - link to viewer pages.
+- Do not present coverage gaps as failures.
+- The briefing must stand alone.
+
+## Finish
+
+- Run `npx hippocampus validate` and reflect its coverage notes in what you report.
+- In live mode, end by asking which role they are in, and give them the section for it.
+- In briefing mode, write `artefacts/onboarding/<date>-orientation.md` and report where it is, which figures it carries, and anything you could not answer because the project context is empty.

package/skills/record-design-decision.skill.md

@@ -9,6 +9,10 @@ reads:
   - node_modules/@hippo-digital/hippocampus/docs/design-actions-and-decisions.md
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/templates/insight-design-action-tracker.xlsx
+  - hippocampus/source/design-actions.json
+  - hippocampus/source/decisions.json
+  - hippocampus/source/relationships.json
+  - hippocampus/source/insights.json
 edits:
   - hippocampus/source/design-actions.json
   - hippocampus/source/decisions.json

package/skills/skills.json

@@ -485,6 +485,34 @@
         "Missing artefacts or unresolved blockers stay visible.",
         "The summary path is reported."
       ]
+    },
+    {
+      "id": "onboard-team-member",
+      "title": "Onboard a team member",
+      "purpose": "Orient someone new to the project from what the knowledge base already knows, and leave them a dated briefing they can read without an agent.",
+      "file": "onboard-team-member.skill.md",
+      "owners": [
+        "knowledge-builder",
+        "workflow-orchestrator"
+      ],
+      "composes": [
+        "ingest-project-context",
+        "audit-knowledge-source"
+      ],
+      "runs": [
+        "npx hippocampus validate"
+      ],
+      "outputs": [
+        "Answers to a new joiner's questions, grounded in the knowledge base",
+        "A dated briefing under artefacts/onboarding/ when one is asked for"
+      ],
+      "acceptance": [
+        "Every figure in the output is derived from the knowledge base, not recalled.",
+        "Narrative claims are attributed, or their absence is stated.",
+        "Each named role has something specific to do next.",
+        "A briefing, if produced, is dated and readable without an agent.",
+        "npx hippocampus validate passes."
+      ]
     }
   ]
 }

package/skills/structure-project-context-draft.skill.md

@@ -8,7 +8,6 @@ owners:
 reads:
   - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - node_modules/@hippo-digital/hippocampus/docs/hippocampus-technical.md
-  - node_modules/@hippo-digital/hippocampus/docs/source-model.md
   - hippocampus/imports/project/[draft-id].review.md
   - hippocampus/imports/project/[draft-id].json
 edits:

package/skills/write-delivery-summary.skill.md

@@ -7,7 +7,6 @@ owners:
 composes:
   - audit-knowledge-source
 reads:
-  - node_modules/@hippo-digital/hippocampus/docs/agent-workflow.md
   - node_modules/@hippo-digital/hippocampus/docs/agent-workflow.md
   - artefacts/delivery-summaries/
 edits:

package/templates/artefacts/README.md

@@ -0,0 +1,23 @@
+# Artefacts
+
+`artefacts/` stores generated review outputs and delivery evidence.
+
+It is not canonical source data. Deleting `artefacts/` should not break the app or the knowledge model.
+
+## Subfolders
+
+- `screenshots/` - dated review packs for routes, screenshots, and per-route notes
+- `accessibility/` - dated review notes with blockers and follow-up improvements
+- `delivery-summaries/` - handover notes for multi-step work
+- `generated-docs/` - importer and AI-generated review drafts
+
+## Naming conventions
+
+Use dated, reviewable paths:
+
+- `artefacts/screenshots/<YYYY-MM-DD>-<topic>/manifest.md`
+- `artefacts/accessibility/<YYYY-MM-DD>-<topic>.md`
+- `artefacts/delivery-summaries/<YYYY-MM-DD>-<topic>.md`
+
+If a workflow cannot produce images, store notes instead of pretending a screenshot exists.
+

package/templates/artefacts/accessibility/README.md

@@ -0,0 +1,30 @@
+# Accessibility review notes
+
+Store one dated note per review run:
+
+```text
+artefacts/accessibility/<YYYY-MM-DD>-<topic>.md
+```
+
+## Suggested sections
+
+- scope
+- routes reviewed
+- blockers
+- improvements
+- unanswered questions
+- manual follow-up
+
+## What to check
+
+Document what was actually reviewed:
+
+- heading order
+- labels and legends
+- link text
+- focus flow and keyboard reachability
+- NHS component usage
+- error-state clarity
+
+If the review is code-based rather than runtime-based, say so explicitly.
+

package/templates/artefacts/delivery-summaries/README.md

@@ -0,0 +1,20 @@
+# Delivery summaries
+
+Store one dated summary per multi-step change:
+
+```text
+artefacts/delivery-summaries/<YYYY-MM-DD>-<topic>.md
+```
+
+Use delivery summaries for handover notes, route reviews, ingestion proofs, and other orchestrated work.
+
+## Include
+
+- request or outcome delivered
+- files changed
+- commands run and their results
+- linked screenshot or accessibility artefacts
+- assumptions, blockers, and follow-up work
+
+Keep summaries concise, factual, and reviewable.
+

package/templates/artefacts/screenshots/README.md

@@ -0,0 +1,30 @@
+# Screenshot review packs
+
+Use one folder per route-review run:
+
+```text
+artefacts/screenshots/<YYYY-MM-DD>-<topic>/
+  manifest.md
+  01-route-slug.png
+  02-route-slug.png
+```
+
+If image capture is not available, keep the folder and write route notes in `manifest.md` instead.
+
+## Manifest checklist
+
+Record:
+
+- review purpose
+- commands run, especially `npx hippocampus doctor`
+- routes reviewed
+- whether each route has an image or notes only
+- issues found
+- routes skipped or still needing manual review
+
+## Conventions
+
+- Prefer one screenshot per route state that matters.
+- Use lowercase route slugs in filenames where practical.
+- Keep fictional data fictional.
+