@hippo-digital/hippocampus 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 1.0.0
+
+First published release.
+
+A design-knowledge base for NHS Prototype Kit projects: research rounds,
+participants, insights and design actions alongside the user needs, scenarios,
+journeys and screens they justify, rendered as a viewer inside your prototype.
+
+### Install and wiring
+
+- `hippocampus init` writes the config and an empty knowledge base, then makes
+  two host edits inside marked, reversible blocks. `--dry-run` shows a diff,
+  `--no-wire` prints the lines instead, `eject` takes them back out and leaves
+  every byte of data.
+- The end marker carries a hash of the block body, so a block your team has
+  edited is reported and left alone rather than overwritten.
+- The `viewsPath` insertion applies only on exactly one match of a plain array
+  of string literals. When it cannot be certain, it writes nothing to that file
+  and prints the lines to paste.
+- The viewer serves its own stylesheet, client JS and layout from its router, so
+  a host needs no sass entry point and no stylesheet link.
+
+### Rooting
+
+- `--root` > `HIPPOCAMPUS_ROOT` > nearest `hippocampus.config.json` > nearest
+  `package.json` outside `node_modules` > cwd, with the winning rule reported.
+- A root resolving inside `node_modules` is a hard error, not a guess.
+- Commands that need a knowledge base refuse when none is found and say where
+  they looked, rather than exiting 0 having done nothing.
+
+### Validation
+
+- Three tiers: errors are broken references, warnings are gaps worth filling,
+  info is coverage. `--strict` promotes warnings to failures.
+- `doctor` checks wiring, integrity and every route, and prints the resolved
+  root first.
+
+### Data contract
+
+- `schemaVersion` 1. Record schemas are passthrough, so fields written by a
+  newer version survive a read and a write; the linter names unrecognised fields
+  so a typo still surfaces.
+- `_meta.json` records the version; absent means 1 and is never invented on
+  read. Data newer than the code is refused rather than read partially.
+
+### Docs and skills
+
+- The 16 guides are served at `{basePath}/docs`, version-matched to the
+  installed package rather than copied into your repo.
+- `skills install` copies the 19 agent skills into `.github/skills` with content
+  hashes, so an upgrade can tell a stale copy from one your team has edited.
+- `init` reports research material in `hippocampus/source-artefacts/` rather
+  than silently committing it; `--private-artefacts` gitignores it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hippo Digital Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @hippo-digital/hippocampus
+
+A design-knowledge base for NHS Prototype Kit projects. It holds the research a
+service is built on - rounds, participants, insights, design actions - alongside
+the user needs, scenarios, journeys and screens those findings justify, and
+renders the whole thing as a viewer inside your prototype.
+
+The point is that a screen can be traced back to the reason it exists: from a
+route, to the needs it meets, to the insights that evidenced them, to the people
+who said so, and forward again to the design actions still open against it.
+
+## Install
+
+```bash
+npm install @hippo-digital/hippocampus
+```
+
+`nhsuk-prototype-kit` and `nhsuk-frontend` are peer dependencies - your project
+already has them, and two copies of the frontend sass in one build is a lost
+afternoon.
+
+## Set it up
+
+```bash
+npx hippocampus init
+```
+
+writes `hippocampus.config.json` and an empty knowledge base, then makes the two
+host edits for you. Both live between markers and are backed up first; a block
+you have since edited is reported and left alone rather than overwritten.
+`--dry-run` shows the diff and writes nothing, `--no-wire` writes the data and
+prints the edits for you to paste, and `npx hippocampus eject` takes the edits
+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
+```
+
+`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.
+
+## Wiring it by hand
+
+Two lines in `app/routes.js`:
+
+```js
+const { createHippocampus } = require('@hippo-digital/hippocampus')
+
+const hippocampus = createHippocampus()
+router.use(hippocampus.router)
+```
+
+and one entry in `app.js`:
+
+```js
+const hippocampus = require('@hippo-digital/hippocampus').createHippocampus()
+
+viewsPath: ['app/views/', hippocampus.viewsPath]
+```
+
+That is all of it. The viewer serves its own stylesheet, client JS and layout
+from its router, so there is no sass entry point to add, no stylesheet link to
+paste into your template, and nothing to re-copy when you upgrade.
+
+## Point it at a project
+
+Add `hippocampus.config.json` at the root of your prototype:
+
+```json
+{
+  "configVersion": 1,
+  "dataDir": "hippocampus",
+  "artefactsDir": "artefacts"
+}
+```
+
+and a `hippocampus/source/project.json`. Everything else is optional - a
+knowledge base with nothing in it boots, renders every route, and tells you what
+to add next.
+
+Commands resolve the project the same way every time:
+
+```
+--root <dir>  >  HIPPOCAMPUS_ROOT  >  nearest hippocampus.config.json
+              >  nearest package.json outside node_modules  >  cwd
+```
+
+A root that resolves inside `node_modules` is an error, not a guess - it would
+otherwise produce an empty knowledge base and no explanation.
+
+## Commands
+
+```bash
+npx hippocampus doctor              # wiring, integrity and routes - start here
+npx hippocampus validate            # parse, check integrity, report coverage gaps
+npx hippocampus validate --strict   # and fail on warnings
+npx hippocampus research triage     # rank a research folder before importing anything
+npx hippocampus research sync       # inbox artefacts to reviewable drafts
+npx hippocampus source index        # record what was ingested, before the copies go
+npx hippocampus migrate             # write a schema upgrade back to disk
+npx hippocampus --help
+```
+
+`validate` reports in three tiers. Errors are broken references. Warnings are
+gaps worth filling - and on a new project, a list of what to do next. Info is
+coverage: nothing is wrong, something is thin.
+
+```
+hippocampus: knowledge data is valid
+  info    51 of 108 insights link to no user need
+  info    108 of 132 needs (82%) sit at priority "medium"
+```
+
+## Documentation
+
+The guides are served by the viewer at `{basePath}/docs`, so they always
+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.
+
+## Keeping research material out of the repo
+
+If your shared drive is the system of record - download into the inbox, extract
+the knowledge, delete the copy - then run:
+
+```bash
+npx hippocampus source index
+```
+
+first. It writes `hippocampus/manifests/source-index.json` and a readable
+`.md` beside it: every artefact's exact filename, size, sha256, which round it
+belongs to, where it was recorded as coming from, and which knowledge records
+cite it. The hash is the part that cannot be recovered later - it is what proves
+a file you find on the drive in a year is the one the findings were drawn from,
+rather than an edited descendant.
+
+It also names the artefacts whose origin was never written down, which is the
+list worth clearing before anything is deleted.
+
+`init --private-artefacts` gitignores the copies once the index exists.
+
+## Data contract
+
+Within a `schemaVersion`, changes are additive and unknown fields survive a read
+and a write - so data written by a newer version of this package still loads in
+an older one. `hippocampus/source/_meta.json` records the version; absent means
+version 1. Data newer than the code is refused rather than read partially,
+because reading forward is how a knowledge base gets destroyed by the next write.

package/assets/dist/hippocampus.css

@@ -0,0 +1 @@
+.knowledge-admin-theme{background:#f6f5f2;font-family:-apple-system,"Segoe UI",Roboto,Arial,sans-serif}.knowledge-admin-theme .nhsuk-header{background:#1c1c1a}.knowledge-admin-theme h1,.knowledge-admin-theme h2,.knowledge-admin-theme h3,.knowledge-admin-theme h4{font-weight:600;letter-spacing:-0.01em}.knowledge-admin-theme .nhsuk-caption-l{color:#706f68;font-size:14px;font-weight:700;letter-spacing:.04em;text-transform:uppercase}.knowledge-admin-theme a{color:#00726b}.knowledge-admin-theme .nhsuk-back-link,.knowledge-admin-theme .nhsuk-back-link__icon{color:#00726b}.knowledge-admin-theme .knowledge-card,.knowledge-admin-theme .knowledge-section,.knowledge-admin-theme .knowledge-blueprint-step,.knowledge-admin-theme .knowledge-linked-block{background:#fff;border-color:#e3e1d9;border-radius:3px;box-shadow:none}.knowledge-admin-theme .knowledge-card__meta,.knowledge-admin-theme .knowledge-muted{color:#8c8a80;font-family:ui-monospace,"SF Mono",Consolas,monospace;font-size:12px;letter-spacing:.03em;text-transform:uppercase}.knowledge-admin-theme .nhsuk-button{background:#1c1c1a;border-radius:2px}.knowledge-admin-theme .nhsuk-button--secondary{background:rgba(0,0,0,0);border-color:#1c1c1a;color:#1c1c1a}.knowledge-admin-theme .nhsuk-tag{border-radius:2px}.knowledge-admin-theme code{background:#e6f6f5;font-family:ui-monospace,"SF Mono",Consolas,monospace}.knowledge-grid{display:grid;grid-template-columns:repeat(auto-fit, minmax(240px, 1fr));gap:16px;margin-top:32px}.knowledge-list{display:grid;gap:16px}.knowledge-card,.knowledge-section,.knowledge-blueprint-step{border:1px solid #d8dde0;padding:24px;margin-bottom:24px;background:#fff}.knowledge-card,.knowledge-linked-block,.knowledge-timeline__item,.knowledge-admin-theme .nhsuk-lede-text{max-width:70ch}.knowledge-section>p,.knowledge-admin-theme .nhsuk-list--bullet,.knowledge-admin-theme .nhsuk-list--number{max-width:70ch}.knowledge-card__meta{color:#4c6272;font-size:16px;margin-bottom:8px}.knowledge-timeline{list-style:none;padding-left:0}.knowledge-timeline__item{border-left:4px solid #005eb8;padding-left:24px;margin-bottom:32px}.knowledge-admin-theme .knowledge-timeline__item{border-left-color:#00726b}.knowledge-blueprint-step__header{align-items:flex-start;display:flex;justify-content:space-between;gap:16px}.knowledge-lane{border-top:1px solid #d8dde0;display:grid;grid-template-columns:220px minmax(0, 1fr);gap:24px;padding:16px 0}.knowledge-lane[hidden]{display:none}.knowledge-lane__label h3{font-size:16px;margin:0}.knowledge-lane__content{max-width:70ch}.knowledge-lane__content>:last-child{margin-bottom:0}.knowledge-boundary{border-top:2px dashed #005eb8;color:#005eb8;font-size:14px;font-weight:700;letter-spacing:.04em;padding-top:8px;text-transform:uppercase}.knowledge-admin-theme .knowledge-boundary{border-top-color:#00726b;color:#00726b}.knowledge-tagged-item{border-left:4px solid #768692;margin-bottom:8px;padding:8px 12px;background:#f0f4f5}.knowledge-tagged-item strong{display:block;font-size:14px}.knowledge-tagged-item--high{border-left-color:#d5281b;background:#fbeae5}.knowledge-tagged-item--medium{border-left-color:#ffb81c;background:#fff9e6}.knowledge-admin-theme .knowledge-tagged-item--high{border-left-color:#8e5300;background:#fdf3e6}.knowledge-admin-theme .knowledge-tagged-item--medium{border-left-color:#ed8b00;background:#fdf3e6}.knowledge-linked-block{border-top:1px solid #d8dde0;padding-top:24px;margin-top:24px}.knowledge-linked-block:first-of-type{border-top:0;padding-top:0;margin-top:0}.knowledge-linked-block__detail{background:#f0f4f5;margin:24px 0;padding:16px}.knowledge-graph-summary{display:grid;grid-template-columns:repeat(auto-fit, minmax(140px, 1fr));gap:12px;margin:24px 0}.knowledge-graph-summary div{background:#f0f4f5;border-left:4px solid #005eb8;padding:12px}.knowledge-admin-theme .knowledge-graph-summary div{background:#e6f6f5;border-left-color:#00726b}.knowledge-graph-summary strong,.knowledge-graph-summary span{display:block}.knowledge-graph-summary strong{font-size:28px;line-height:1}.knowledge-graph-summary span{color:#4c6272;font-size:14px;margin-top:4px}.knowledge-graph{display:grid;grid-template-columns:repeat(auto-fit, minmax(220px, 1fr));gap:12px;margin-top:24px}.knowledge-graph__node{border:1px solid #d8dde0;border-top:4px solid #768692;padding:12px}.knowledge-graph__node strong,.knowledge-graph__node span{display:block}.knowledge-graph__node strong{color:#4c6272;font-size:14px;margin-bottom:4px}.knowledge-graph__node span{font-size:16px}.knowledge-graph__node--user{border-top-color:#005eb8}.knowledge-graph__node--scenario{border-top-color:#d5281b}.knowledge-graph__node--need{border-top-color:#007f3b}.knowledge-graph__node--evidence{border-top-color:#7c2855}.knowledge-admin-theme .knowledge-graph__node--scenario{border-top-color:#330072}.knowledge-admin-theme .knowledge-graph__node--need{border-top-color:#006747}.knowledge-graph__node--journey,.knowledge-graph__node--screen,.knowledge-graph__node--decision{border-top-color:#ffb81c}.knowledge-edge-list{display:grid;gap:8px}.knowledge-edge-list li{background:#f0f4f5;display:grid;grid-template-columns:minmax(0, 1fr) auto minmax(0, 1fr);gap:12px;padding:12px}.knowledge-edge-list span{color:#4c6272;font-size:14px;font-weight:700;text-transform:uppercase}.knowledge-trace-controls{display:flex;flex-wrap:wrap;align-items:flex-end;gap:16px 24px;margin-bottom:0}.knowledge-trace-controls__field{display:flex;flex-direction:column;width:100%;max-width:320px}.knowledge-trace-controls__field .nhsuk-label{margin-bottom:4px}.knowledge-trace-controls__submit{margin:0}.knowledge-trace-timeline,.knowledge-trace-children{list-style:none;margin:0;padding-left:0}.knowledge-trace-timeline{position:relative}.knowledge-trace-timeline::before{background:#005eb8;bottom:0;content:"";left:13px;position:absolute;top:8px;width:4px}.knowledge-trace-group,.knowledge-trace-item{position:relative}.knowledge-trace-group{padding-left:48px}.knowledge-trace-group__content{margin-bottom:24px}.knowledge-trace-group__content h3{margin-bottom:16px}.knowledge-trace-children{display:grid;gap:16px}.knowledge-trace-children .knowledge-trace-children{border-left:2px solid #d8dde0;margin-top:16px;padding-left:24px}.knowledge-trace-item{padding-left:48px}.knowledge-trace-item__marker{background:#fff;border:4px solid #005eb8;border-radius:50%;height:20px;left:3px;position:absolute;top:4px;width:20px}.knowledge-trace-children .knowledge-trace-item__marker{border-color:#768692}.knowledge-trace-item__content{max-width:70ch;border-top:1px solid #d8dde0;padding:16px 0 8px}.knowledge-trace-item--selected .knowledge-trace-item__content{background:#f0f4f5;border-left:4px solid #005eb8;border-top:0;margin:8px 0 32px;padding:16px}.knowledge-trace-item--selected .knowledge-trace-item__marker{background:#005eb8}.knowledge-admin-theme .knowledge-trace-timeline::before{background:#00726b}.knowledge-admin-theme .knowledge-trace-item__marker{border-color:#00726b}.knowledge-admin-theme .knowledge-trace-children .knowledge-trace-item__marker{border-color:#768692}.knowledge-admin-theme .knowledge-trace-item--selected .knowledge-trace-item__content{border-left-color:#00726b}.knowledge-admin-theme .knowledge-trace-item--selected .knowledge-trace-item__marker{background:#00726b}.knowledge-trace-item__date{color:#4c6272;font-size:16px;font-weight:700;margin-bottom:4px}.knowledge-trace-item__heading{font-size:22px;margin:0 0 8px}.knowledge-trace-item__type{display:inline-block;padding:2px 10px;margin-bottom:8px;font-size:14px;font-weight:700;color:#fff;background:#768692;border-radius:12px}.knowledge-trace-item__type--user{background:#005eb8}.knowledge-trace-item__type--scenario{background:#d5281b}.knowledge-trace-item__type--need{background:#007f3b}.knowledge-admin-theme .knowledge-trace-item__type--scenario{background:#330072}.knowledge-admin-theme .knowledge-trace-item__type--need{background:#006747}.knowledge-trace-item__type--evidence{background:#7c2855}.knowledge-trace-item__type--journey,.knowledge-trace-item__type--screen,.knowledge-trace-item__type--decision{color:#212b32;background:#ffb81c}.knowledge-trace-item__relationship{color:#4c6272;font-size:16px;margin-bottom:4px}.knowledge-trace-item__relationship strong{color:#212b32}.knowledge-muted{color:#4c6272}.knowledge-confidence-tag{display:inline-block;padding:2px 8px;font-size:13px;font-weight:700;border-radius:10px}.knowledge-confidence-tag--high{color:#00726b;background:#e6f6f5}.knowledge-confidence-tag--medium{color:#00758f;background:#e6f6fa}.knowledge-confidence-tag--low{color:#4c6272;background:#f0f4f5}.knowledge-matrix-wrap{overflow-x:auto}.knowledge-matrix{border-collapse:collapse;min-width:1200px;width:100%}.knowledge-matrix th,.knowledge-matrix td{border:1px solid #d8dde0;padding:12px;text-align:left;vertical-align:top}.knowledge-matrix thead th,.knowledge-matrix tbody th{background:#f0f4f5}.knowledge-matrix__boundary td{border-top:2px dashed #005eb8;color:#005eb8;font-weight:700;text-transform:uppercase}.knowledge-admin-theme .knowledge-matrix__boundary td{border-top-color:#00726b;color:#00726b}.knowledge-blueprint-controls{position:sticky;top:0;z-index:2;display:flex;flex-wrap:wrap;gap:16px 24px;align-items:flex-start;padding:12px 0;margin-bottom:24px;background:#fff;border-bottom:1px solid #d8dde0}.knowledge-blueprint-controls__lenses{display:flex;flex-wrap:wrap;gap:8px}.knowledge-lens-btn{padding:6px 14px;font:inherit;color:#005eb8;background:#fff;border:2px solid #005eb8;border-radius:20px;cursor:pointer}.knowledge-lens-btn[aria-pressed=true]{color:#fff;background:#005eb8}.knowledge-admin-theme .knowledge-lens-btn{color:#00726b;border-color:#00726b}.knowledge-admin-theme .knowledge-lens-btn[aria-pressed=true]{background:#00726b}.knowledge-blueprint-controls__lanes{display:flex;flex-wrap:wrap;gap:8px 16px;padding:0;margin:0;border:0}.knowledge-blueprint-controls__lanes legend{width:100%;font-size:14px;font-weight:700}.knowledge-lane-toggle{display:inline-flex;align-items:center;gap:4px;font-size:14px}.knowledge-blueprint-layout{display:grid;grid-template-columns:72px 1fr;gap:24px}.knowledge-blueprint-minimap{position:sticky;top:64px;align-self:start}.knowledge-blueprint-minimap ul{position:relative;padding:0;margin:0;list-style:none}.knowledge-blueprint-minimap ul::before{position:absolute;top:16px;bottom:16px;left:15px;width:2px;content:"";background:#d8dde0}.knowledge-blueprint-minimap li{position:relative;margin-bottom:16px}.knowledge-blueprint-minimap a{position:relative;display:block}.knowledge-blueprint-minimap__marker{display:flex;align-items:center;justify-content:center;width:32px;height:32px;font-weight:700;color:#005eb8;background:#fff;border:2px solid #005eb8;border-radius:50%}.knowledge-blueprint-minimap a.is-active .knowledge-blueprint-minimap__marker{color:#fff;background:#005eb8}.knowledge-admin-theme .knowledge-blueprint-minimap__marker{color:#00726b;border-color:#00726b}.knowledge-admin-theme .knowledge-blueprint-minimap a.is-active .knowledge-blueprint-minimap__marker{background:#00726b}.knowledge-blueprint-step{scroll-margin-top:88px}.knowledge-flow-diagram{overflow-x:auto;padding:24px;margin-bottom:24px;background:#fff;border:1px solid #d8dde0}.knowledge-flow-source{overflow-x:auto;white-space:pre}.knowledge-admin-theme .knowledge-flow-diagram{border-color:#e3e1d9;border-radius:3px}@media(max-width: 48.0525em){.knowledge-blueprint-layout{display:block}.knowledge-blueprint-minimap{position:static;margin-bottom:16px}.knowledge-blueprint-minimap ul{display:flex;flex-wrap:wrap;gap:8px}.knowledge-blueprint-minimap ul::before{display:none}.knowledge-blueprint-minimap li{margin-bottom:0}.knowledge-lane{grid-template-columns:1fr;gap:8px}.knowledge-edge-list li{grid-template-columns:1fr}.knowledge-trace-controls{grid-template-columns:1fr;gap:0}.knowledge-trace-timeline::before{left:9px}.knowledge-trace-group,.knowledge-trace-item{padding-left:36px}.knowledge-trace-item__marker{height:16px;left:1px;width:16px}}.knowledge-admin-theme .knowledge-empty-state{max-width:70ch;padding:24px;margin-bottom:24px;background:#fff;border-left:4px solid #aeb7bd}.knowledge-admin-theme .knowledge-empty-state h2{margin-top:0}.knowledge-admin-theme .knowledge-empty-state p:last-child{margin-bottom:0}.knowledge-admin-theme .knowledge-doc{max-width:76ch;padding:24px 32px;background:#fff}.knowledge-admin-theme .knowledge-doc h1{margin-top:0}.knowledge-admin-theme .knowledge-doc h2,.knowledge-admin-theme .knowledge-doc h3{margin-top:32px}.knowledge-admin-theme .knowledge-doc pre{padding:16px;overflow-x:auto;background:#f6f5f2;border-left:4px solid #aeb7bd}.knowledge-admin-theme .knowledge-doc code{font-size:15px}.knowledge-admin-theme .knowledge-doc table{width:100%;margin-bottom:24px;border-collapse:collapse}.knowledge-admin-theme .knowledge-doc th,.knowledge-admin-theme .knowledge-doc td{padding:8px 12px;text-align:left;vertical-align:top;border-bottom:1px solid #d8dde0}