Maintenance

Knowledge-Base Operating Model

The wiki is a structured evidence-and-synthesis system for InterSystems healthcare guidance, decisions, delivery, research, and assurance. Every durable page should support a useful conclusion, supply source evidence, define an architecture or operating model, or identify a boundary that prevents safe conclusions.

Do not record final guidance as a research priority. Research priorities are the unresolved evidence gaps, synthesis gaps, implementation gaps, and confidence limits that block reliable guidance.

Keep page roles separate:

Source Register: provenance and source inventory in docs/sources.md.
Evidence Matrix: claim-level support, confidence, and limitations in docs/evidence-matrix.md.
Evidence Validation Queue: To Do items, blockers, assumptions, and unresolved boundaries in docs/evidence-validation-queue.md.
What Next register: suggestion provenance, plain-English purpose, relevance, scope and disposition in docs/what-next.md; links to canonical gaps and outputs rather than duplicating evidence.
Research Log: Done items, completed passes, findings, and decisions in docs/log.md.
Synthesis Pages: human-readable current working positions under docs/knowledge-base/.
Architecture / Model Pages: system, process, policy, domain, or implementation structure under the relevant module or evidence-domain area.
Glossary: maintained terms, acronyms, aliases, and definitions in docs/knowledge-base/glossary.md.
Operational / LLM Wiki: maintenance rules, conventions, starter instructions, and agent guidance in docs/llm-wiki/.
Generated indexes, graph views, and tool outputs: navigation and discovery aids, not source truth.

OKF Compatibility Boundary

The Open Knowledge Format (OKF) is a useful compatibility and exchange pattern for Markdown knowledge bundles, but it is not the governing evidence model for this wiki. The current local model is stricter than OKF: Source Register, Evidence Matrix, Evidence Validation Queue, Research Log, synthesis pages, architecture/model pages, LLM operational notes, and generated discovery artifacts have separate roles.

Use OKF as an optional export or compatibility profile, not as a source of evidence authority. OKF can add typed page metadata, portable concept IDs, traversal hints, validation checks, and a cleaner handoff surface for sibling projects or external agents. It does not add evidence, improve source reliability, replace Graphify, replace sources.md or evidence-matrix.md, or guarantee that consumers preserve this project's evidence discipline.

The default non-destructive implementation is a generated sidecar bundle, for example okf-out/intersystems-wiki/, produced from canonical docs/ pages. Keep docs/ as the source of truth. If an OKF sidecar is generated, keep it outside docs/ unless MkDocs, generated-index, and Graphify ingestion behavior is explicitly updated. Generated OKF files must not be mistaken for new source evidence or allowed to make Graphify ingest its own publication/export artifacts.

An in-place OKF profile across the Markdown files is mechanically feasible, even with roughly 125 files, but the cost is semantic churn rather than edit volume. OKF conformance expects frontmatter on concept documents and gives reserved meaning to index.md and log.md; this wiki already uses those filenames for MkDocs navigation, module indexes, the home page, and the Research Log. Before any in-place conversion, run the structure stop/go rule in docs/source-evidence-domain-map.md, prototype representative files, and verify MkDocs, Graphify, generated indexes, and source/evidence role separation.

Suggested OKF type values, if a profile or export is built, should mirror local page roles instead of inventing a parallel taxonomy: Source Register, Evidence Matrix, Evidence Validation Queue, Research Log, Synthesis Page, Evidence Domain, Architecture Model, Operational Note, Generated Index, and Graph View.

Anchor-Page Discipline

Use docs/llm-wiki/context-map.md as the current anchor-page register. Before changing a domain, check the affected anchor pages first. If a source changes the current model, update the relevant anchor page, related synthesis pages, evidence records, validation queue, research log, glossary, and operational notes in the same pass where practical.

Separate user-facing outcomes, source systems, integration routes, policy constraints, data dependencies, assurance requirements, and implementation status. Do not collapse distinct evidence categories into generic labels. Where a claim depends on a specific system, interface, policy, cohort, process, role, supplier, jurisdiction, or implementation stage, name that dependency explicitly.

Core Services Summary and Matrix

The national-service reading order is UK Core Services Executive Summary → UK Core Services Matrix → UK Healthcare Connectivity Landscape, followed by country detail. The summary remains an independent entry point immediately before the matrix; it provides the quick comparison and Access labels. The matrix owns detailed functional comparison; the landscape explains layers, national routes, programmes and separately evidenced supplier roles. Keep section entry links consistent with these roles and this order. Source evidence belongs in the country/service pages and canonical registers, not a second evidence inventory in the summary.

Whenever the summary, matrix, landscape or supporting evidence changes, reconcile all three in the same pass. Preserve the matrix’s 43 unique functions and summary’s 38 grouped comparison rows; the two repeated safeguarding rows in each page do not add unique functions. Keep pathology ordering immediately before pathology results, imaging ordering immediately before imaging reports/images, and professional viewing separate from patient viewing. Check named system-to-system (System) routes, portal workflows, local configuration, unverified interfaces, access restrictions and rollout status. System includes documented APIs, messages and automated feeds; it does not establish public onboarding, full-record scope, Med IS availability or InterSystems implementation. Networks and policy frameworks are not clinical interfaces. Keep all six user-reported Current Med IS service markers synchronised across the matrix and summary, independently of the Access labels. The summary’s Healthcare network row makes HSCN visible alongside SWAN, PSBA and HSC WAN; all four network Access values are Other because they describe transport, not clinical interfaces.

npm run check:core-services-summary compares a recorded SHA-256 digest with the summary body, excluding its acknowledgement marker, and 11 source pages: the matrix, landscape, four country pages, diagnostic exchange, GP2GP record transfer, terminology code management, DSIC standards/national services and the DSIC capability crosswalk. It runs in npm run check and therefore CI verification. A changed summary or source, missing marker or malformed/duplicate marker fails the gate. Structural checks require both comparison pages to contain five topic tables (core services; access/registration/GP transactions; urgent care; safety/prevention/care planning; coding/reporting/payments), a separate DSIC explanation and a substantive cross-border list or table. Each page’s Safeguarding subsection must repeat its own two source rows exactly. Paired Med IS checks require the same six stable marker keys in their mapped England service cells and the same dated legend. These checks also run before recording, but semantic correctness still requires manual review. Reconcile the pages first, then explicitly record the reviewed state:

npm run check:core-services-summary -- --record-review

The summary must visibly cover the five comparison topics, Using DSIC as the Comparison Lens, and What Actually Crosses Borders in the same order as the matrix. Both pages repeat the existing child-protection and FGM rows under a Safeguarding subsection within Safety, Prevention and Care Planning. Keep those repeats identical to their original rows in each page, including access and evidence limits; do not count them as new functions. Keep its rows concise; do not replace a requested topic with a link-only mention. For nation comparison tables, author the exact nine-column Function | England | Access | Scotland | Access | Wales | Access | Northern Ireland | Access pattern. The presentation hook groups each nation over its Service and Access columns. Those two subheadings use regular weight; nation headings and body Access values retain their existing emphasis. Access columns inherit the standard wiki table separators; do not add cell outlines or vertical borders. Use System for a documented API/message/feed (the former S2S label), Portal for a person-operated application, and Local, Files, Other, Planned or Unverified where relevant. Mixed routes may use System<br>Portal, with the service text identifying which route each label describes. Keep beta, restricted, deprecated and local-only qualifiers in the description; an unverified interface is not proof of absence.

Current Med IS uses the existing light-teal service-cell highlight and visible accessible tick, never the Access column or its label. Each page has six data-med-is markers: england-pds, england-ods, england-pathology-edifact, england-ers, england-mesh and england-hscn. The summary places separate e-RS and MESH ticks within its combined Referrals and documents cell, so its six markers occupy five highlighted service cells; the matrix retains six service cells. The single legend on each page carries data-med-is-date="2026-09-21" and the visible 21 September 2026 date. The pathology marker applies only to EDIFACT over MESH and excludes the separate FHIR reporting pilot. Unmarked cells do not assert that Med IS lacks the service. These annotations repeat the user’s report, not new source verification or supplier assurance. Missing, unknown or duplicate marker keys, incorrect cell mapping, or invalid or unequal ISO legend dates, or visible report dates that disagree with that metadata block both checking and review recording.

The review marker is an editorial acknowledgement, not proof of semantic correctness. It must never refresh automatically during builds or kb:update. Extend the script’s dependency list if the summary comes to rely directly on another canonical page. Distinguish the summary reconciliation date from external-source review dates: keep the core baseline and later extensions visible without claiming fresh external research. This workflow does not schedule source monitoring.

Evidence And Terminology Discipline

Put direct evidence first, adjacent implementation evidence second, and wider contextual evidence only when it changes 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.

Expand important acronyms and specialist terms at first use on each page. Keep glossary entries, aliases, navigation labels, presentation rules, and tests aligned where automated rendering or linking depends on terminology. Use project-standard names consistently, and record deliberate variants where sources use different wording.

When a visible synthesis table uses a source-layer acronym or shorthand label, link it to the canonical source-layer page or section. For healthcare-recording source layers, use docs/knowledge-base/modules/healthcare-record-source-layers.md as the routing map. Create a new source-layer page only when the label is repeated, decision-relevant, or needed to explain an evidence boundary; otherwise link to an existing canonical page or keep the source ID in the Source Register.

Keep docs/evidence-matrix.md and docs/evidence-validation-queue.md source-ID-first. Do not convert every repeated source-layer label in canonical registers into a visible link; add reader-facing links only for rows that define a reusable route, synthesis boundary, or decision-facing source-layer model.

Status Discipline

Use the visible To Do / Done model consistently:

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 Contract

After every substantive response, include a What Next section with exactly three numbered steps. Each step should be discrete, high-impact, actionable in one follow-up pass, and tied to a wiki page or project artifact where possible. Include rendered wiki URLs for referenced or updated wiki pages when the local or published wiki URL is available.

Balance those three steps as a small portfolio unless the user explicitly asks to stay inside one trail: one step should close or advance the current evidence gap, one should update or test the affected anchor model, and one should broaden the work to an adjacent source/evidence domain. Avoid repeatedly deepening the same queue item, including West Midlands, DUAA, ICO guidance, or any other active thread, unless there is new evidence, a scheduled trigger, a response to an outstanding request, or a direct user instruction. Treat Source and Evidence Domain Map, Evidence Validation Queue, and Context Map as background controls rather than default What Next recommendations; mention them only when the next step is a concrete edit, gate decision, or validation action on that artifact.

Do not use one of the three What Next slots for a passive trigger condition, "wait until a source appears" statement, or generic maintenance reminder. Those belong in the response summary, Evidence Validation Queue, Research Log, or affected synthesis page. A valid What Next item must name work that can actually be performed in the next pass, such as a current-source search, source-register update, evidence-matrix reconciliation, anchor-page audit, rendered verification, or scoped synthesis edit.

Before returning the three steps, record or reconcile them in What Next: Suggestions and Decisions. Use stable WN identifiers, link to the relevant entry, and merge repeated outcomes. Capture purpose, origin/date, relevance, status, destination and completion criterion. Do not imply that suggested work is selected or that an unverified interface must be resolved. On selection mark in progress; on completion, merge or retirement retain a short disposition and link to the result/Research Log. Detailed evidence targets remain in the existing queue. The initial import is bounded to recoverable conversation suggestions and documented wiki priorities, not every historical chat.

Sibling-Project Reuse

Use the reusable standards-conformance evidence request pattern on docs/evidence-domains/standards-interoperability.md as a cross-project assurance mechanic. It applies when a certificate, register, validation row, supplier-progress row, standards claim, or product conformance statement could be over-read as deployment proof. Apply it to one live assurance claim at a time, starting from docs/evidence-validation-queue.md, and convert the claim into product/version, validation scope, exclusions, component coverage, adjacent standards, and deployment artefact requests on the relevant synthesis page.

Do not add another request pack when a plain link to the reusable pattern would be enough. A new pack is justified only when the claim is actively being used for assurance, procurement, delivery, research decisions, or implementation planning and the evidence needed differs materially from the existing pattern or worked examples. Otherwise, keep the gap in the Evidence Validation Queue and reference the canonical pattern.

Before creating any new page, checklist, request pack, or evidence-domain layer, run the stop/go and traversal-friction check in docs/source-evidence-domain-map.md. New structure is justified only when it reduces repeated traversal or turns an active assurance claim into a concrete evidence request. A single unresolved artefact, supplier response, FOI target, standards row, or generic concern should stay in its existing module or queue entry until a real assurance decision, new source, response trigger, or repeated traversal pressure changes the evidence state.

The sibling-project equivalent prompt lives in docs/llm-wiki/starter-instruction.md. Use that prompt in a target project's root agent instructions or starter wiki artifact before its next evidence pass rather than creating another project-agnostic request-pack page here.

Update Process

Add or update source material.
Update synthesis pages only with supported claims.
Record the research pass in docs/log.md.
Regenerate generated artifacts with npm run kb:update when Graphify is available.
If Graphify is unavailable, regenerate the code index with npm run kb:code-index and record the limitation in docs/log.md.
Run npm run verify.
Commit every file-changing development pass with jj commit.
In this colocated Git-backed repository, move the main bookmark to the committed change when the pass is intended to advance main, then verify Git sees the same clean state.
Before handoff, confirm git status --short, jj status, and Git push state.

Page History and Non-Destructive Editing

Keep one current Markdown page per topic. Git is the published source of truth; this colocated Git-backed JJ repository already preserves tracked pages at committed revisions. Separate dated copies of every wiki page are unnecessary. Retain meaningful editorial passes as pushed commits, and preserve unique evidence, material qualifications and working links in the current wiki when reorganising text. Historical wording alone is not an adequate home for still-relevant knowledge.

Distinguish three mechanisms:

Committed content history: Git/JJ can inspect and recover earlier committed page versions. This records committed revisions, not every editor save.
Local recovery: JJ snapshots the working copy during most JJ operations and provides an operation log for repository-state recovery. It is not continuous editor autosave; ordinary Git pushes do not preserve the JJ operation log. Backing up that recovery history requires the local repository metadata, including .jj. See the official working-copy and operation-log documentation.
Reader-visible history: MkDocs currently presents the current pages without a configured page-history interface. The GitHub repository is private, so a GitHub history link would require collaborator access. Last substantive evidence review, last file edit and published version are different metadata fields.

Wiki version history does not preserve the contents of linked external webpages. Selective dated source captures, with provenance, are a separate evidence-preservation task; existing product-image provenance does not constitute a general source archive. Reader-visible history and capture requirements remain future work, not implemented features.

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.

The GitHub Actions wiki workflow runs npm run verify, including the Graphify freshness check. CI must therefore install both requirements.txt for the MkDocs site and requirements-tools.txt for the pinned Graphify CLI, and both manifests must participate in the pip cache key. Do not fold Graphify into the site-runtime requirements or skip the freshness gate.

Cloudflare Pages is the production publishing target; GitHub Pages is not enabled for this repository. After npm run verify, publish the built site/ directory to the existing intersystems-wiki project with npx wrangler pages deploy site --project-name intersystems-wiki --branch main from a clean, pushed commit. Do not enable a second GitHub Pages site without an explicit hosting decision.

Local Serve

On Andrew's macOS workstation, the wiki is kept running by the user LaunchAgent com.andrew.intersystems-wiki at /Users/andrew/Library/LaunchAgents/com.andrew.intersystems-wiki.plist. It runs /Users/andrew/Projects/InterSystems/.venv/bin/mkdocs serve -a 127.0.0.1:8002 from the repository root, starts at login, and restarts if the process exits.

Useful commands:

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

Logs are written to /Users/andrew/Library/Logs/InterSystemsWiki/mkdocs.out.log and /Users/andrew/Library/Logs/InterSystemsWiki/mkdocs.err.log.

Cloudflare Ask Wiki

The optional Ask page lives at docs/llm-wiki/ask.md and is published as /llm-wiki/ask/. Its browser code in docs/assets/ask-wiki.js retrieves candidate pages from Material's generated search/search_index.json, sends selected excerpts to /api/ask, and renders the returned answer with retrieved page links.

The /api/ask route is implemented as a Cloudflare Pages Function in functions/api/ask.js. It uses the Workers AI binding named AI, an optional ASK_WIKI_SHARED_SECRET Pages secret, and the ASK_WIKI_MODEL variable in wrangler.jsonc. The 2026-06-25 runtime-confirmed model is @cf/meta/llama-3.1-8b-instruct-fp8. The Function does not crawl GitHub or read private repository content at runtime; it answers from the excerpts supplied by the published wiki page.

Use npm run verify before any Wrangler preview or deployment. For local Cloudflare testing, run npx wrangler whoami and then npx wrangler pages dev site --ai=AI from the repository root after a strict build so Wrangler can see the root functions/ directory. Load /llm-wiki/ask/ from the Wrangler Pages URL, not the MkDocs LaunchAgent URL, because the Ask page calls same-origin /api/ask.

The 2026-06-25 Wrangler test used npm exec --yes --package wrangler@4.105.0 -- wrangler pages dev site --ai=AI --port 8788. After Cloudflare OAuth was refreshed, Wrangler reported env.AI as a remote AI binding and /api/ask returned a Workers AI answer with citations from the supplied wiki excerpt. The first test also showed that @cf/meta/llama-3.1-8b-instruct is deprecated as of 2026-05-30; keep the default on a current model and recheck the model catalog before future changes.

The production deployment is https://intersystems-wiki.pages.dev/ on Cloudflare Pages project intersystems-wiki; the initial production verification was completed on 2026-06-26. A deployed Ask test against https://intersystems-wiki.pages.dev/api/ask returned HTTP 200 with an answer and citations for the question "How does the Cloudflare Ask path retrieve wiki content, and which Workers AI model is runtime-confirmed?" Production ASK_WIKI_SHARED_SECRET is set in Cloudflare Pages, so unauthenticated /api/ask requests return 401 and the Ask page Access key field is required.

Ask answers should be moderately expansive by default: enough context, caveats, and reasoning to be useful, while staying limited to the retrieved excerpts and cited page paths. Keep this balance in the Ask Function before increasing retrieval complexity.

Lexical retrieval against Material's generated search index is sufficient for the initial personal-experiment path because it avoids Vectorize setup, embedding cost, and an ingestion pipeline while keeping every answer tied to rendered wiki pages. The 2026-06-26 deployed test retrieved the right operational pages and produced a correctly cited answer, while also retrieving a few broad wiki pages. Reassess Vectorize only after real questions show recurring misses from synonyms, cross-page synthesis, or top-excerpt quality that lexical ranking cannot fix.

Ask snippets should anchor on the densest query-token window rather than the first matching generic product token. This keeps broad table excerpts from starting at an unrelated row when a later country or organisation row is the relevant evidence. The Ask Function also instructs the model to treat table rows, country sections, organisations, products, and settings as independent evidence units so evidence from one country or customer is not used to support another.

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 Home; Products and Services, UK NHS Digital Connectivity and Interoperability Evidence, Standards and Interoperability, and NHS England Digital Primary Care should remain first-class sections rather than being nested behind generic chrome wrappers. GP Connect now belongs under NHS England Digital Primary Care with DSIC.

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.

For main sections that have an overview page, keep the first child title equal to the section title. Material only renders some same-title children as section index links natively, so docs/assets/nav-section-indexes.js generically promotes same-title first child links into selectable section-title links and hides the duplicate child item. Inactive top-level section titles should be muted grey; the active top-level section title should stay accent-colour and bold while selected child pages remain normal weight.

Nested primary-sidebar groups should expand inline from the label without showing Material's chevron icon. docs/assets/nav-section-indexes.js binds these labels as keyboard-accessible toggle controls and removes their native hidden-checkbox label target so the hidden icon is not required.

The sidebar outline rail feature has three terms: page outline means Material's integrated table of contents, section outline means a visible nested page list, and outline rail means the shared positioned accent bar. The page outline is the visual source of truth, and both outline types should share the same positioned rail model and accent-colour rail tokens, including rail width, child-text padding, clipping, optical text trim, and vertical extent. Use --wiki-nav-rail-start-offset and --wiki-nav-rail-end-offset to trim the rail visually toward the first and last text rows without changing list layout. Reset Material's negative .md-nav bottom margin on inline nested primary groups so the last child row does not overlap the next sibling section. When an active child page injects an integrated page outline, keep the outer section rail continuous and let the page outline rail nest inside it; do not reintroduce a mask or split over the section rail.

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.

On desktop, the primary sidebar is offset upward by --wiki-sidebar-top-correction so the page-top state matches the sticky after-scroll position. Recheck this in the browser after changing theme, header, or navigation CSS.

The desktop Material grid is intentionally full-width via --wiki-page-max-width: none in docs/assets/theme.css. The page table of contents is integrated into the primary sidebar with toc.integrate, so the theme should not reserve a separate right-side TOC rail. Keep the integrated page-outline indicator bar tied to --wiki-accent, the shared positioned rail model, clipping behavior, and the --wiki-nav-rail-* tokens shared with section outlines. Remove Material's secondary-nav border physically with direction-specific border resets; setting only a transparent border colour leaves a real gutter offset. Hide Material's generated secondary-nav TOC title inside the primary sidebar so it does not reserve a spacer above the first heading row. Keep rail trim visual-only so sibling page links after a TOC retain the page-list rhythm.

The desktop header search box uses --wiki-header-search-right-correction, derived from --wiki-content-right-inset and --wiki-header-right-inset, to align its right edge with the article content's right inset rail. Recheck this at desktop widths when changing header padding, page grid width, or content margins.

The desktop active header page title uses --wiki-header-title-left-offset, derived from --md-sidebar-width, --wiki-content-left-inset, and --wiki-header-title-leading-chrome, so the visible page title aligns with the article content's left inset rail. Recheck this at desktop widths when changing logo sizing, header buttons, page grid width, or content margins.

Reader-facing evidence pages should state boundaries as evidence findings rather than instructions to the reader. Prefer "the current evidence supports..." or "the current evidence does not show..." over directive phrases such as "do not describe", "do not infer", or "treat X as" in visible wiki prose.

Markdown content bullet lists use custom square accent-colour markers through --wiki-list-marker-size, --wiki-list-marker-gap, --wiki-list-marker-top, and --wiki-accent. Keep these rules scoped to .md-typeset ul:not([class]) so navigation and Material component lists retain their own layout.

Rendered article tables with a Country / setting column are formatted at build time by hooks/presentation_rules.py: values split around the first /, the country uses the muted bold .wiki-table-country line, and the setting remains normal text on the next line. Keep the Markdown source as plain Country / setting text unless the source itself needs different semantics.

Rendered article links inside .md-content are styled in docs/assets/theme.css with teal text and cloned accent-highlight boxes, excluding Material heading anchors, button-style links, footer links, and other Material chrome from both article-link colour and highlight rules. The highlight outsets use em tokens so links in tables and other smaller text scale proportionately. Keep hover and keyboard-focus underline enabled as the active affordance.

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 plus maintained aliases when they appear as plain text in article content outside headings, table headers, code/pre, buttons, and existing links. When a generated title link resolves to the current page, render it as non-clickable .wiki-self-reference text with subtle accent tint and a non-layout horizontal visual outset instead. Keep source IDs in Markdown so the source trace remains available to maintainers and generated indexes.

Product-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 InterSystems ... and HealthShare ... product-name rules as the product-family prefix followed by a protected product tail so narrow table and nav cells can break at the family boundary without splitting the product name tail.

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 product-name phrase wrapping. CSS selector scope for article links, footer links, and Material chrome is covered by tests/test_theme_css.py.

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

Use raw HTML anchors for Graphify full-screen Material buttons, matching <a class="md-button md-button--primary" href="../../assets/graphify/..." target="_blank" rel="noopener">... full screen</a>. Do not use Markdown attribute-list button syntax on these pages; this wiki has previously rendered that syntax as literal { .md-button ... } text in article content.

When Graphify link, button, or footer/chrome styling regresses, run npm run smoke:graphify-rendered against the local wiki server. The script checks the rendered Graphify overview, 2D, and 3D pages plus theme.css; set GRAPHIFY_SMOKE_BASE_URL if the local server is not http://127.0.0.1:8002.

The publisher adds explicit Markdown-link edges as links to relationships, source-reference edges from page citations to SRC-### nodes, Source Register definition edges, MkDocs nav contains edges, repository filesystem contains edges, and explicit references file edges from docs/config to mentioned repository files. These are source-backed, path-backed, or configuration-backed relationships, not inferred semantic relationships, and are used to connect otherwise isolated document and code islands in both the 2D and 3D views.

Graphify community detection can assign volatile numeric community IDs between otherwise equivalent runs. The publisher remaps communities deterministically before writing browser graph assets, and the freshness checker normalizes the raw GRAPH_REPORT.md community-order section while still checking counts and generated graph assets.

Group source-backed nodes by source file and external nodes without a source file by stable node ID. Name those external groups from the node label/ID; raw numeric community IDs must not enter published keys or labels. The September 2026 registration clarification exposed this edge case for HTMLParser between local and CI clustering. Preserve the freshness gate and regression test instead of accepting a stochastic rerun as proof of determinism.

npm run check:graphify regenerates Graphify in a temporary copy of the repository. It should not delete the live docs/assets/graphify/graph.html file that the in-app browser may be viewing.

Mermaid Diagrams

Mermaid support is enabled through pymdownx.superfences custom fences in mkdocs.yml, a pinned browser runtime (mermaid@11.15.0 from jsDelivr), and docs/assets/mermaid-init.js.

docs/assets/mermaid-init.js reads the wiki design CSS variables and passes them into Mermaid theme variables. Keep rendered diagram fills, borders, edges, and text aligned with the DESIGN.md accent-colour contract rather than Mermaid's default palette.

Mermaid diagram node links use click directives with _self targets so the whole rendered node behaves as normal wiki navigation. Mermaid documents that click links require securityLevel: "loose"; keep diagram sources controlled local wiki content and use site-relative wiki URLs.

Keep Mermaid labels short on rendered wiki pages. Put long interface names, proof requirements, source caveats, and governance detail in adjacent tables or prose so diagrams do not overlap or become unreadable in the in-app browser.

UK Platform Estate Dataset

data/uk-platforms/records.json is the canonical observation dataset, with sources, ICB crosswalk, generalised boundaries and provenance beside it. The generator scripts/build-platform-atlas.mjs validates links/IDs/geography and renders marked table sections plus CSV/JSON/GeoJSON under docs/assets/uk-platforms/. Edit prose outside generated markers; edit records once at source. npm run platforms:build regenerates outputs; platforms:check rejects drift and is included in verify. kb:update builds the atlas before the no-API index and Graphify.

Leaflet 1.9.4 is an exact npm input installed with scripts disabled for this pass; official stable release information was checked. The MkDocs hooks/platform_atlas.py post-build hook verifies the version and copies runtime/licence from node_modules into site assets. CI must run npm ci before MkDocs. Do not place third-party minified code in the Graphify corpus or add a remote tile service without revisiting the map contract. Keep ODS organisational IDs separate from ONS boundary IDs and local NI map codes. Dataset dates describe source evidence, not production testing.