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.
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.

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.

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.

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

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 2026-06-26 production deployment is https://intersystems-wiki.pages.dev/ on Cloudflare Pages project intersystems-wiki. 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.

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 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.

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.