Skip to content

Maintenance

Update Process

  1. Add or update source material.
  2. Update synthesis pages only with supported claims.
  3. Record the research pass in docs/log.md.
  4. Regenerate generated artifacts with npm run kb:update when Graphify is available.
  5. If Graphify is unavailable, regenerate the code index with npm run kb:code-index and record the limitation in docs/log.md.
  6. Run npm run verify.
  7. Commit every file-changing development pass with jj commit when JJ is configured for this repository.
  8. Before handoff, confirm git status --short, jj status when available, and Git push state when a remote exists.
  9. In the final response for every wiki/content update, include rendered wiki URLs for the updated pages or components using the local MkDocs server base [local preview URL]. Do not substitute filesystem Markdown links for these user-facing wiki links.

Hosting and publication

Private source: denchco/dmedc-nhs-app. Public target: https://dmedc-nhs-app.pages.dev/, using explicit Pages Direct Upload in the existing Andrew Dench account. The owner confirmed the scope in publication.json on 23 October 2026, including LLM Wiki and public-content Graphify views. mkdocs.yml builds the complete local wiki to site/; mkdocs.public.yml filters the allowlisted publication into site-public/. Do not deploy site/.

Run npm run build:public and inspect output/publication/inventory.json. The public build excludes IRTB(P) pages and assets (including the IRTB(P) LLM build context), retained Word/history/previews, revision tools, project operations and the research log. LLM Wiki and Graphify are published. The public graph retains only nodes sourced from allowlisted files and edges between them; it discards full-repository metadata, private nodes and edge excerpts, and rebuilds the 2D payload, labels and counts. The full local graph remains intact. Retained records must remain unchanged. New pages are private by default. Public synthesis can still discuss proposals and internal evidence boundaries; removal of original files is not removal of the same topic from public prose.

Wrangler 4.151.3 is the only new deployment dependency. Full verification and public-boundary checks precede the JJ commit and private Git push. npm run deploy checks scope confirmation, clean Git state and the remote commit, rebuilds the public site, verifies its file hashes, links and search entries, and checks authentication before uploading. GitHub Actions verifies only; it does not deploy or store Cloudflare credentials. See Deployment (internal reference) for the release and rollback procedure.

Pages rejects account_id in wrangler.jsonc. The deployment script selects the existing account through CLOUDFLARE_ACCOUNT_ID; keep account selection out of the Pages configuration file.

Defence digital content standard

Treat docs/knowledge-base/modules/defence-digital-content-and-writing-standard.md as the user-facing content contract. The MOD Defence Service Manual requires GOV.UK content principles and styles for internal as well as citizen-facing digital services.

For new or materially revised wiki content:

  • include only content that supports a user need, decision, evidence claim, architecture/model, action or explicit boundary;
  • use plain English, short sentences and paragraphs, active voice, and the user's domain language;
  • use one clear H1, ordered semantic heading levels and sentence case unless a proper name or protected military term requires another form;
  • make link text meaningful out of context; do not use click here, here, more or raw URLs as labels where a descriptive title is available;
  • expand unfamiliar acronyms on first use on every page and keep the glossary, presentation hook, browser fallback and tests aligned for maintained terms;
  • preserve authoritative military and NATO terminology and source-specific programme wording;
  • do not rely on colour, shape, size or location alone; add alternative text, captions or legends where needed;
  • confirm classification, marking and publication controls before adding Defence information; and
  • apply the rule to pages being created or materially changed without introducing unrelated whole-wiki wording churn during a narrow evidence pass.

For the IRTB(P), use the same plain-English and accessibility principles, but treat the current internal JSP 101, approved template, classification, staffing and issuing-authority instructions as controlling where document conventions differ.

The retained IRTB(P) document controls A4 geometry and the Arial 12 visual system. Use scripts/format_irtbp_docx.py with the workspace dependency Python to apply the durable DOCX contract to outputs/NHS App IRTBP - capability business case draft.docx. The formatter keeps metadata, main headings and subsection labels unnumbered; numbers substantive body prose continuously; letters true subordinate options; prefixes annex prose; left-aligns all section, subsection and annex titles; applies 12 points before and after subsection labels, 12 points after main headings and annex titles, and 12 points after every numbered body paragraph, lettered option and numbered annex paragraph; keeps To, From and Date at single line spacing with 4.5 points after; lets the bold Title line wrap at single line spacing with 12 points after; bolds semantic paragraph lead-ins through their first full stop; and can emphasise named NHS App features without turning their explanatory text bold. Four body pages remain the final target, but the active working draft may use five to preserve required content. After a document change, run tests/test_irtbp_docx.py, render all pages with the document skill, and visually inspect the current body and four annex pages before delivery.

Before any material IRTB(P) rewrite or Word build, reconcile three controlling artefacts:

  1. IRTB(P) Construction (internal reference) controls the human document, layout, voice, audience, option, and staffing rules.
  2. IRTB(P) Evidence Brief (internal reference) controls the current argument, evidence boundaries, options, and recommendation.
  3. IRTB(P) Build Context (internal reference) controls machine-readable generation.

Do not build the Word document while those three disagree. Keep internal Phase 0-6 labels out of the staffed paper.

The IRTB(P) version history and AI review contract (internal reference) also applies to smaller wording passes. The local editor captures settled inline edits and explicit checkpoints into append-only text records; npm run kb:irtbp-editor retains applied canonical source changes. Never edit or delete retained records. Use npm run history:verify to check the archive, and commit retained versions through the usual JJ workflow. Browser recovery copies and the Word generation boundary remain separate. A static site deployment can view the archive but cannot accept repository writes.

Before a material rewrite replaces the generated Word output, preserve the prior output in docs/assets/irtbp-history/ and register it on docs/knowledge-base/modules/irtbp-version-history.md. Treat archived DOCX files as immutable. Add a new revision when the decision sought, option set, recommendation, argument order, evidence position, page structure or annex content changes materially; record the source Git revision and SHA-256 checksum. Do not use the archive as current synthesis: the generated output, IRTB(P) Evidence Brief and IRTB(P) Construction page remain the current document and build contract.

The Word history catalogue follows the Digital Healthcare Delivery project's export-provenance and separate-preview patterns. Run npm run kb:irtbp-word-history after retaining a new Word revision; npm run kb:update includes it. The generated docs/assets/irtbp-word-history/index.json binds every R-number to the original DOCX, immutable text record, file checksum, observed Word review features and exact matching saved text. Equality does not establish causal ancestry. No existing archive record is rewritten to add these relationships. npm run history:verify checks all retained Word bytes against both their immutable records and SHA256SUMS, plus catalogue freshness and any retained render bundles.

Keep the existing two-stage capture: reconcile the browser head into the canonical source, run npm run kb:irtbp-editor, build and visually verify Word, retain the new Word revision/checksum and commit its exact output bytes, then run npm run kb:irtbp-history to capture Git provenance. A source save alone is not a Word export. Do not enable Track Changes or manufacture review comments retrospectively in retained files; export metadata reports the actual settings and review elements present.

To retain page previews, render the archived DOCX with the bundled document runtime and inspect every page. Run scripts/retain_irtbp_word_preview.py REVISION --render-dir PATH --renderer LABEL --review-note NOTE with that runtime's Python, then regenerate the Word catalogue. The retention tool refuses to replace an existing preview bundle. The bundle records the original DOCX checksum, PDF and page-image checksums, page dimensions, renderer and explicit visual-review note. New renders of an already retained preview require a separately retained revision, not replacement of its files. The current R35 bundle contains six body pages and four annex pages from bundled LibreOffice. It does not claim Microsoft Word layout verification.

docs/assets/irtbp-word-history.js shares the read-only export panel between editor and history. The editor compares the current text SHA-256 to retained Word transcription hashes. Every text change immediately removes previous preview pages and controls; asynchronous responses must still match the active text selection before display. Previewing and returning to editing do not save, restore or publish. Downloads and displayed preview assets must pass their recorded checksums. On a missing catalogue or preview error, text editing and text history remain usable. Word changes made outside this archive are not captured until the user supplies them for reconciliation.

Knowledge-Base Wiki Operating Pattern

Use this generic pattern for KB wiki projects. The project-specific starter instruction should fill in the domain, anchor pages, evidence categories, and build commands.

Continue the [PROJECT_NAME] source-linked knowledge-base wiki.

Purpose and direction:
This wiki exists to inform [GUIDANCE / DECISIONS / DELIVERY / RESEARCH / ASSURANCE] for [DOMAIN]. Do not treat the end guidance itself as a research priority; treat research priorities as the evidence gaps, synthesis gaps, implementation gaps, and confidence limits that prevent reliable guidance. Every page should either support a useful conclusion, supply source evidence, define the relevant architecture or operating model, or identify a boundary that prevents safe conclusions.

Knowledge-base architecture:
Maintain the wiki as a structured evidence-and-synthesis system, not a loose note set. Keep these roles distinct:
- Source Register: provenance and source inventory.
- Evidence Matrix: claim-level support, confidence, and limitations.
- Evidence Validation Queue: To Do, unresolved evidence gaps, blockers, assumptions, and boundaries.
- Research Log: Done, completed passes, findings, and decisions made.
- Synthesis Pages: human-readable conclusions and current working position.
- Architecture / Model Pages: system, process, policy, domain, or implementation structure.
- Glossary: maintained terms, acronyms, and definitions.
- Operational / LLM Wiki: maintenance rules, project conventions, starter instructions, and agent guidance.
- Generated indexes / graph views / tool outputs: navigation and discovery aids, not source truth.

Controlling synthesis:
Identify and maintain one or more anchor pages that define the project's current model. Every related pass must be checked against those anchor pages. If a new source changes the model, update the anchor page, affected synthesis pages, evidence records, validation queue, research log, glossary, and operational notes as needed.

Architecture rules:
Separate user-facing outcomes, source systems, integration routes, policy constraints, data dependencies, assurance requirements, and implementation status. Do not collapse distinct components or evidence categories into a generic label. Where a claim depends on a specific system, interface, policy, cohort, process, role, supplier, jurisdiction, or implementation stage, name that dependency explicitly. Do not preserve a fine-grained label merely because it exists: keep route-family or component labels only when they change confidence, applicability, evidence required, assurance requirements, or guidance status; otherwise use the wider provider-route, general PEP, or broader component wording.

Evidence discipline:
Put direct evidence first. Then add adjacent implementation evidence. Then add wider contextual evidence only where it changes the interpretation. Preserve source wording where terminology is time-specific, disputed, or evolving. Distinguish confirmed facts, inferred relationships, open questions, assumptions, and options for future validation.

Evidence request pack discipline:
Use evidence request packs sparingly. They add value when a live assurance, procurement, delivery, research, or implementation claim needs concrete evidence such as product/version, validation scope, exclusions, component coverage, adjacent standards, or deployment artefacts. They overcomplicate the knowledge base when they multiply as generic checklists without a live decision use case.

Before adding any new page, checklist, request pack, or evidence-domain layer, run a stop/go check:
- Does it reduce repeated traversal across module pages, source register, evidence matrix, and validation queue?
- Does it turn an active assurance claim into a concrete evidence request?
- Would a link to the existing reusable pattern or a queue entry be enough?

If the answer is no, do not create new structure. Keep the gap in the Evidence Validation Queue, link to the reusable pattern, and update the relevant synthesis or anchor page only where the current model changes.

Status discipline:
Use a visible To Do / Done model. To Do belongs in the Evidence Validation Queue or equivalent blocker register. Done belongs in the Research Log or equivalent completed-work register. Current synthesis belongs in the relevant synthesis or anchor page. Operational rules belong in the LLM / maintenance documentation.

Response rule:
After every substantive response, include a What Next section with exactly three numbered steps. Treat this as a whole-project-aware triage, not only a continuation of the latest thread and not a full fresh audit every time. Before choosing steps, check the visible status model, current anchor pages, evidence queue, work packages, and adjacent source/evidence domains.

Balance the three steps unless the user asks otherwise:
1. a closure step for the current evidence gap, implementation gap, or validation item;
2. an anchor-model step for the affected synthesis, decision, architecture, or status page;
3. a breadth step into the next adjacent source/evidence domain that matters for project confidence.

Each step must be discrete, high-impact, actionable in one follow-up pass, and tied to a wiki page or project artifact where possible. Do not repeatedly deepen the freshest unresolved thread without a new trigger from evidence, source response, scheduled recheck, or user instruction. Include rendered wiki URLs for referenced or updated wiki pages when a local or published wiki URL is available.

Cycle guard:
Before writing What Next, ask whether the latest thread has already reached a bounded, parked, or direct-evidence-needed state. If yes, avoid using the closure step to keep pursuing that same trail unless a new trigger exists. Reassess the total KB gap landscape across decision, architecture, evidence, source-freshness, and implementation pages, then rotate to the next decision-blocking gap. Continuing one topic is valid only where the next pass can close a concrete gap or update a controlling anchor; otherwise the topic stays in the Evidence Validation Queue.

Whole-Project What Next Add-On Prompt

Use this add-on prompt for this wiki and sibling source-linked KB wiki projects, including the InterSystems / openIPS wiki. Fill in the project-specific URL base, anchor pages, and domain terms before use.

For every substantive response, produce a whole-project-aware `What Next` section with exactly three numbered steps. Do not treat `What Next` as only the next action in the latest thread, and do not perform a full project audit unless asked.

Before choosing the steps, quickly check the project's visible status model, current anchor pages, evidence queue, evidence work packages, research log, and adjacent source/evidence domains. In user-facing responses, use rendered wiki URLs from [WIKI_BASE_URL] for wiki pages, not filesystem Markdown links.

Run a cycle guard before writing the steps. If the latest trail is already bounded, parked, or blocked pending direct evidence, do not keep selecting it as the next closure step unless new evidence, a source response, a scheduled recheck, or the user explicitly triggers that trail. Reassess the total KB gap landscape and rotate to the next decision-blocking gap. Continue one topic only when the next pass can close a concrete gap, change confidence, or update a controlling anchor.

Balance the three steps:
1. Closure: the most important action that would close or narrow the current evidence gap, implementation gap, validation queue item, or confidence limit.
2. Anchor model: the synthesis, decision model, architecture page, project status page, or other anchor that must be updated or checked so the current work changes the wiki's durable model.
3. Breadth: the next adjacent source/evidence domain that should be rotated into view, especially where it could change interpretation, confidence, assurance, or guidance.

Do not repeatedly deepen the freshest unresolved trail unless new evidence, a source response, a scheduled recheck, or the user explicitly triggers that trail. Treat sibling-wiki material as cross-deck synthesis until primary source IDs, source wording, and carry-over controls are present in the receiving wiki.

Status and Handoff

The visible status page is docs/project-status.md. It maps To Do to docs/evidence-validation-queue.md, Done to docs/log.md, current synthesis to the relevant anchor pages, and operational rules to this LLM wiki and AGENTS.md.

Before handoff, check whether a completed pass has changed:

  • To Do: update docs/evidence-validation-queue.md when evidence gaps, blockers, or boundaries move.
  • Done: update docs/log.md when a research or implementation pass completes.
  • Current synthesis: update the controlling synthesis page when the working model changes.
  • Operating rules: update AGENTS.md, docs/project-ops/agents.md, this page, and docs/llm-wiki/starter-instruction.md when durable workflow rules change.

Tool and Dependency Lifecycle

Treat every external tool and dependency as a versioned input. Check local versions, committed manifests, package managers, and upstream release notes before changing workflow assumptions.

Local Serve

Suggested development command:

.venv/bin/mkdocs serve -a 127.0.0.1:8003

On Andrew's macOS workstation, the wiki is kept running by the user LaunchAgent com.andrew.dmedc-nhs-app-wiki at [local path withheld]. It runs [local path withheld] from the repository root, starts at login, and restarts if the process exits.

launchctl print gui/$(id -u)/com.andrew.dmedc-nhs-app-wiki
launchctl kickstart -k gui/$(id -u)/com.andrew.dmedc-nhs-app-wiki
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.andrew.dmedc-nhs-app-wiki.plist

Logs are written to [local path withheld] and [local path withheld].

The pinned MkDocs 1.6.1 server loads hooks/irtbp_capture.py, which mounts the local version API and suppresses live-reload injection on the editor and history tools so autosave cannot reload a draft mid-edit. Other wiki pages retain live reload. Restart the LaunchAgent after changing this hook or its API module. The integration uses the documented MkDocs serve event and the inspected 1.6.1 live-reload method; recheck that method before any intentional MkDocs upgrade.

Every IRTB(P) toolbar action uses the shared native button helper and centred layout in docs/assets/irtbp-editor.css. Restore and JSON download actions must retain whole-box pointer interaction, matching hover/focus/disabled states and native Enter/Space activation. Keep history versions read-only; restoration navigates to the editor, which captures a new version.

The inline editor recognises complete pipe tables and renders semantic table, thead, th scope="col" and td elements with editable cell textboxes. tableModel retains original cell offsets and rewrites only edited cell text, escaping pipes and converting line breaks to <br>; separators, alignment markers and untouched cells remain exact. Cells use the existing safe bold renderer. Pagination keeps rows whole and repeats synchronised editable headers. Oversized individual rows scroll inside the sheet. Use Markdown mode for row/column structure; malformed tables remain editable source text. Verify all four annex tables (105 cells), source round trips, cell edits/saves, literal pipes, line breaks, bold, undo, repeated-header edits, multi-page tables and mobile containment when changing this path. Table padding is --wiki-irtbp-table-cell-padding: 1mm; three-column annex widths are 22/37/41 percent of the page text area.

Inline **text** emphasis renders as editable strong nodes with the --wiki-irtbp-bold-weight token. readInline serialises edited text back to Markdown; renderInline recognises completed bold spans without importing HTML and maps the caret across hidden delimiters. Page fragments retain only their original opening/closing markers, so emphasis can continue across sheets without adding source markers. Ordinary edits inside bold text keep native editing behaviour; composition finishes before reformatting. Verify typing new emphasis, editing existing emphasis, Markdown and autosave round trips, literal escaped/code text, and emphasis across page boundaries when changing this path.

The inline editor uses 210 × 297 mm A4 sheets with 20 mm margins on all sides, defined by the --wiki-irtbp-page-* tokens in docs/assets/theme.css. The page text area is 170 mm wide with Arial 12 pt type; avoid per-block ch widths and auto margins. Numbered and annex paragraphs place their marker and wrapped lines at the page text margin, with first-line text 10 mm in. Lettered subparagraphs place their marker and wrapped lines 10 mm in, with first-line text 20 mm in. These first-line offsets use --wiki-irtbp-first-line-offset and --wiki-irtbp-subparagraph-indent; do not apply hanging indents. Fixed-width marker spans preserve source spaces and tabs without using them to size the visual gap. A missing separator before an uppercase prose or bold start (for example 1.MOD-registered or a.**Option**) still receives the marker inset, without silently changing the saved source; decimals remain literal. Verify deleting the separator and editing immediately after the marker; subsequent page fragments align with the marker position without repeating it. paginateDocument measures the 257 mm content height, starts annexes on new sheets, keeps headings with the next paragraph where possible, and splits oversized blocks into editable display fragments without inserting source separators. Content reflows after focus leaves the document; active editing keeps the caret stable and any temporary overflow inside the page content area. Narrow screens scroll across the full-size sheet. Browser page breaks reflect visible Markdown and do not replace the separately generated Word layout. Verify page dimensions, first and wrapped line positions, margin containment, complete source preservation and inline-to-Markdown round trips when changing this component.

Revision Tools

Revision tooling is retained as optional scaffold material but hidden from this project's visible navigation through not_in_nav. If it is surfaced later, progress remains browser-local and should not contain sensitive data.

Keep the MkDocs sidebar organised around the real content domains. Entry pages belong under Start Here; NHS App Service, Architecture and Components, and Defence Medical Command (DMedC) / Defence Primary Healthcare (DPHC) Continuation and/or Adoption should remain first-class sections rather than being nested behind generic chrome wrappers. The NHS App Service section can include a compact Service Architecture page before access-model pages when diagrams are needed to connect the service overview to component dependencies. The Architecture and Components section should keep Interface and Assurance Layer visible with the component pages so supplier interfaces, API/Message Exchange for Social Care and Health (MESH) routes, and onboarding controls are not buried inside feature pages.

The Material primary sidebar title is intentionally hidden because it duplicates the header brand and consumes the first navigation row. Keep the sidebar starting with real navigation entries.

Primary sidebar labels wrap rather than truncate. When a long MkDocs nav label needs a deliberate phrase break, add a targeted selector in docs/assets/theme.css using the existing --wiki-nav-wrap-tight, --wiki-nav-wrap-medium, or --wiki-nav-wrap-wide tiers. Prefer stable href selectors for linked pages; use generated label IDs only for collapsible nav groups that MkDocs renders without an href.

Rendered citation and title presentation is handled at build time by hooks/presentation_rules.py, with docs/assets/phrase-wrap.js retained as an idempotent browser-side fallback for Material navigation. The rules hide parenthetical SRC-### citation lists, remove exact source-ID heading variants, remove source-labelled table columns whose body cells are only SRC-### lists, and auto-link known navigation page titles, first Markdown # H1 titles for nav targets, and maintained aliases when they appear as plain text in article content outside headings, table headers, code/pre, buttons, and existing links. When a prose label should link but is neither a nav label nor the target page's H1, add a maintained alias in both the build hook and browser fallback, then cover it in tests/test_presentation_rules.py.

Service-name phrase wrapping is handled by the build-time hook and by docs/assets/phrase-wrap.js plus .wiki-nowrap in docs/assets/theme.css. Keep known NHS, GP Connect, Spine, DMedC, and DPHC phrases aligned between the hook and browser fallback.

First-use acronym expansion is a build-time presentation rule in hooks/presentation_rules.py. A glossary row by itself is passive; for rendered pages to explain a term where it first appears, the acronym must be present in the hook's acronym registry, have any needed navigation/title aliases, and be covered by tests/test_presentation_rules.py. Keep docs/knowledge-base/glossary.md, the hook registry, the browser fallback alias/context list in docs/assets/phrase-wrap.js, and the tests aligned when adding or changing maintained acronyms such as Personal Demographics Service (PDS), Organisation Data Service (ODS), DMedC, Defence Medical Services (DMS), DPHC, Spine Secure Proxy (SSP), Spine Directory Service (SDS), Interface Mechanism 1 (IM1), MESH, Service Conformance Assessment List (SCAL), Model Interface Licence (MIL), Electronic Prescription Service (EPS), Patient Engagement Portal (PEP), Patient Engagement Portals (PEPs), Secondary healthcare (SHC), HealthShare Unified Care Record (UCR), or Enterprise Master Patient Index (EMPI).

Use .evidence-status chips only for validation workflow status. Keep the statuses aligned with docs/evidence-validation-queue.md and the semantic variants in docs/assets/theme.css.

Presentation behavior is covered by tests/test_presentation_rules.py. Add tests there when changing build-time source-ID cleanup, source-column removal, auto-linking, or phrase wrapping.

Evidence Placement

Treat the whole wiki as an evidence base for DMedC / DPHC NHS App guidance. Each page should either support a guidance-relevant conclusion, supply source evidence for that conclusion, or identify a boundary that prevents safe guidance. Do not let research strands become detached background unless they change what the guidance could say.

Keep detailed annual-report and source-series interpretation on the relevant evidence-strand page. Feature pages should cite those pages briefly and state the feature-specific implication, rather than duplicating report-series narrative. For Armed Forces Covenant annual reports, present direct NHS App evidence first, then Programme CORTISONE / Op CORTISONE / MOD digital-health material, then wider interoperability and patient-record context. Preserve source wording for Programme Cortisone, Programme CORTISONE, and Op CORTISONE; use neutral analytic phrasing such as "the CORTISONE programme" when not citing a specific source form.

For eligibility, minors, dependants, and linked profiles, keep own NHS App access separate from proxy / linked-profile access. Use the public NHS age bands and GP-practice setup rules as the ordinary NHS baseline, then mark DPHC Firmbase, DPHC Overseas [DPHC(O)], and split ordinary NHS GP / DPHC family registrations as unresolved unless a direct source confirms behaviour. Do not treat "dependant" as a standalone eligibility category.

Treat docs/knowledge-base/modules/guidance-decision-model.md as the guidance-facing answer surface, docs/knowledge-base/modules/registration-state-model.md as the cohort/registration classifier, and docs/knowledge-base/modules/nhs-app-adoption-implementation.md as the context anchor for each future pass that touches NHS App adoption, continuation of use, DPHC cohorts, NHS App architecture, feature availability, CORTISONE, or InterSystems cross-deck evidence. Every adjacent feature, source, architecture, or implementation update should be checked against those pages and the phased model: initial provision, SHC appointments, Defence Medical Information Capability Programme (DMICP) Primary healthcare (PHC) appointment visibility, DMICP PHC appointment management, clinical correspondence, test results, then later CORTISONE patient data. Keep SHC appointment / PEP evidence separate from DMICP / DPHC PHC appointment visibility and management. For DMICP PHC appointment visibility claims, require both the source feed contract and the NHS-facing display route; NHS Notify can support messages and Patient Care Aggregator / PEP evidence can support secondary-care routes, but neither proves PHC visibility by itself. For DMICP PHC appointment management claims, require bidirectional write-back, slot/schedule state, conflict handling, patient/proxy permissions, audit, supplier/practice enablement, and completed NHS-facing route assurance; treat management as likely not available at this stage on current public evidence. Keep clinical correspondence evidence separated from test-result evidence: correspondence routes include SHC / provider document routes, PEP document routes, and GP-filed document views; test-result routes include GP-filed result views, provider systems, PEP results-release routes, and later CORTISONE patient data. Treat HealthShare Unified Care Record, Health Connect / Integration Platform, EMPI, IM1, and GP Connect Patient Facing APIs as evidence targets for later CORTISONE integration, not proof of NHS App feature availability.

Use docs/knowledge-base/modules/architecture-index.md as the architecture hub. Use docs/evidence-work-packages.md to operationalise validation items, docs/source-freshness.md to classify source volatility, and docs/cross-deck-evidence-carry-over.md before promoting InterSystems sibling wiki synthesis.

Open sources do not expose DMICP appointment capabilities, API contracts, integration patterns, or adaptation / evolution options. Keep adapter, wrapper, replacement, CORTISONE transition, and write-back possibilities as unknown until direct MOD, DMedC / DPHC, supplier, or NHS implementation evidence is available.

DPHC Terminology

Use DPHC Firmbase for domestic UK MOD Defence Primary Healthcare care. For overseas MOD Defence Primary Healthcare care, use DPHC Overseas [DPHC(O)] on first page use and DPHC(O) after that. When comparing registration routes, distinguish ordinary NHS GP, MOD DPHC Firmbase, and DPHC(O) models rather than using generic "MOD, NHS, and overseas" wording.

NHS App Architecture Terms

Use Patient Care Aggregator / Wayfinder for the NHS App secondary-care referral and booking aggregation service. Use PEP only after expanding or clearly defining it as Patient Engagement Portal; distinguish Wayfinder-connected PEPs from general provider patient portals. Treat NHS Notify as the message-sending service and NHS App messaging as one delivery/channel experience, not the same component. Treat Spine Directory Service, Interface Mechanism 1, IM1 Pairing, IM1 PFS Auth, MESH, Pairing and Integration Packs, Service Conformance Assessment Lists, Model Interface Licence, and partner onboarding as lower interface / assurance evidence, not direct proof of DPHC NHS App feature availability.

Graphify

npm run kb:update regenerates the code index, removes old published Graphify artifacts plus local graphify-out, runs Graphify from a fresh working output, and republishes browser assets. The publisher post-processes the committed browser graph so communities are named from their dominant source file and representative node rather than left as numeric Community N labels.

Graphify publication emits wiki-embedded 2D and 3D views:

  • docs/assets/graphify/graph.html
  • docs/assets/graphify/graph-3d.html
  • docs/assets/graphify/graph.json
  • docs/assets/graphify/summary.json

scripts/check-graphify-freshness.mjs compares regenerated Graphify output with committed artifacts. It checks stable graph content while normalising volatile display metadata: community IDs, community names, node colours, embedded 2D graph arrays, report title/date, commit freshness text, and community report ordering.

Mermaid Diagrams

Mermaid support is enabled through MkDocs Material's native Mermaid integration using pymdownx.superfences custom fences in mkdocs.yml. docs/assets/mermaid-render.js is also loaded as an idempotent fallback: after page load, Material document updates, or live DOM replacement, it renders any remaining raw pre.mermaid blocks so users do not see Mermaid source code in the wiki.

Mermaid architecture diagrams are styled through Material's Mermaid CSS variables on the .mermaid host in docs/assets/theme.css, using NHS blue for node borders, connector lines, and arrow markers, with light blue node fills and page-background edge labels. hooks/presentation_rules.py injects a pre-bundle script that opens Mermaid shadow roots for diagrams only, sets SVG rx / ry attributes on .node rect elements from the global --wiki-diagram-node-radius value, currently 4px, and applies --wiki-diagram-font-size, currently 11px, to generated SVG and foreignObject labels. Direct .mermaid svg selectors do not affect the preferred Material-rendered diagram because Material puts Mermaid SVG inside a shadow root; the fallback renderer may render directly into pre.mermaid only when Material has not already converted the block.

The same presentation hook injects a default Mermaid init directive into rendered flowchart, graph, and sequence blocks that do not already declare one. The default uses 11px diagram text, compact flowchart spacing, and compact sequence text. Do not add page-local Mermaid init directives for ordinary sizing; use an authored init only when a specific diagram genuinely needs to override the global wiki default, and browser-check the affected rendered page afterward.

scripts/check-mermaid.mjs is wired into npm run verify as npm run check:mermaid, after npm run check:mkdocs. It scans every Markdown Mermaid fence under docs/, confirms required architecture pages still contain their expected diagrams, compares source diagram count with the built MkDocs output, checks built pages for Mermaid error markers, confirms built pages with Mermaid blocks load assets/mermaid-render.js, and rejects flowchart labels with any single rendered line over 42 characters.

The check guards known Mermaid failure modes that render as raw source/error blocks or unreadable diagram nodes in the browser: actor Patient stick-man lifelines, unquoted sequence participant aliases with punctuation, raw semicolons in sequence message/note text, overlong flowchart label lines, source/build diagram-count drift, and built-page Mermaid error markers. Architecture Index and NHS App Service Architecture are required Mermaid pages and should remain covered whenever diagrams are moved or split.

After diagram-heavy edits, perform a browser spot check at mobile width on the affected rendered wiki pages. The automated source/build smoke test catches known parse and build drift issues; the browser check confirms client-side Mermaid rendering and mobile layout.

Alternative Diagram Tools

Keep Mermaid as the default for simple sequence diagrams and compact route sketches, because it is already wired into MkDocs Material and keeps diagrams editable in Markdown.

Do not treat Mermaid limitations as a reason to replace Mermaid everywhere. Split the diagram problem by purpose:

  • Keep Mermaid for simple sequence diagrams, route sketches, and compact flowcharts where source-controlled Markdown is more valuable than fine layout control.
  • Use D2 for higher-density executive, architecture, and component diagrams where layout, spacing, text wrapping, and stable SVG output matter. D2 is not a JavaScript diagramming library, but it is the best current fit for this wiki's static MkDocs pages because it is declarative and can render checked-in SVG from source.
  • If a JavaScript-only route is required, use ELK.js with custom SVG or app code for controlled architecture layout. ELK.js is a layout engine, not a diagram authoring language, so it should be used only where the hard problem is automatic graph layout.
  • Use Cytoscape.js for interactive graph or network exploration, not executive diagrams.
  • Use React Flow / xyflow only if the project is building an interactive React diagram explorer or editor, not for ordinary static MkDocs pages.
  • Avoid GoJS unless commercial licensing and a richer diagramming application are acceptable. Treat JointJS similarly: the core library may be usable for app-style diagrams, but JointJS+ and advanced tooling introduce product and licensing considerations.

Use Graphviz DOT where strict directed-graph layout is the main requirement. Use Structurizr DSL only if the wiki needs a formal C4 model with multiple views generated from one architecture source. Use Kroki only as a renderer layer when it is self-hosted or otherwise controlled; do not send unpublished MOD/NHS synthesis diagrams to a public renderer.

The Phase 0-6 roadmap prototype in docs/assets/diagrams/phase-0-6-roadmap-d2.d2 was rendered with D2 v0.7.1 to docs/assets/diagrams/phase-0-6-roadmap-d2.svg. It is a comparison asset, not a build dependency. User review rejected making it canonical for the Executive Summary because the Mermaid visual style is preferred; keep the Mermaid Executive Roadmap as the user-facing version unless explicitly directed otherwise. If D2 is adopted elsewhere, add an explicit render/check step so .d2 and .svg cannot drift.

Current tool-selection rule:

Diagram type Default tool Switch when
Linear route / sequence model Mermaid sequence diagram The route needs multiple variants, dense branching, or a non-sequence executive view.
Compact system flow Mermaid flowchart Text sizing or box layout needs repeated post-render fixes.
Executive roadmap or component architecture D2 static SVG The diagram is box-heavy, needs stable visual layout, or should render without Mermaid shadow-DOM styling.
Interactive exploration / generated layouts ELK.js with custom SVG or app code The wiki needs dynamic filtering, expansion, or graph layout beyond a static SVG.
Network exploration Cytoscape.js The task is to explore, filter, or interact with a graph/network, not to present a stable executive diagram.
Diagram editor / interactive React surface React Flow / xyflow, JointJS, or GoJS The project is building a diagramming application; check licensing and app-maintenance cost first.

Architecture Index review:

Architecture Index diagram Current decision Reason
Account and GP-Linked Feature Route Keep Mermaid Linear dependency chain; Mermaid sequence remains readable.
Direct NHS App Web Integration Route Keep Mermaid Short logical sequence with limited participants.
Secondary Healthcare Appointment Route Keep Mermaid Still a compact SHC route; reconsider D2 only if provider variants multiply.
Provider Document and PEP Document Route Keep Mermaid Sequence makes the document-route boundary clear.
Provider Results and PEP Results-Release Route Keep Mermaid Sequence makes the release-control boundary clear.
DMICP PHC Appointment Visibility Candidate Route Keep Mermaid for now Candidate route is compact; move to D2 if feed, transform, and display variants split.
DMICP PHC Appointment Management Candidate Route D2 / split-page candidate Write-back, slot, conflict, proxy, and assurance branches could outgrow a sequence diagram if evidence arrives.
CORTISONE / InterSystems Enablement Candidate Route D2 candidate Layered component/route model is already box-heavy and likely to gain branches.
NHS Notify Message Route Keep Mermaid Simple message/fallback path.
Prescription Route Keep Mermaid Linear request-to-dispensing path until DPHC prescribing variants are evidenced.

Reference points: