dxcomplete 0.1.0

package/src/mcp/docs.ts

@@ -0,0 +1,557 @@
+export const DOC_SOURCE_BASE_URL = "https://dxcomplete.directeddomains.com";
+
+export const DOC_PAGE_IDS = ["start_here", "outcomes", "flow", "records", "roles", "glossary"] as const;
+
+export type DocPageId = (typeof DOC_PAGE_IDS)[number];
+
+type BaseDocPage = {
+  page: DocPageId;
+  title: string;
+  sourceUrl: string;
+  summary: string;
+};
+
+type StartHereDoc = BaseDocPage & {
+  page: "start_here";
+  phases: Array<{
+    number: string;
+    name: string;
+    description: string;
+  }>;
+};
+
+type OutcomesDoc = BaseDocPage & {
+  page: "outcomes";
+  outcomes: Array<{
+    name: string;
+    description: string;
+  }>;
+  transformationValue: Array<{
+    state: string;
+    focus: string;
+    description: string;
+  }>;
+  goodLooksLike: Array<{
+    statement: string;
+    description: string;
+  }>;
+};
+
+type FlowDoc = BaseDocPage & {
+  page: "flow";
+  phases: Array<{
+    number: string;
+    name: string;
+    description: string;
+    sourceUrl: string;
+  }>;
+};
+
+type RecordsDoc = BaseDocPage & {
+  page: "records";
+  routingGuidance: {
+    principle: string;
+    sharpTest: string;
+    axes: Array<{
+      name: string;
+      test: string;
+    }>;
+    routingOrder: Array<{
+      signal: string;
+      record: string;
+    }>;
+    edgeCases: string[];
+    promotion: string;
+    futureContainers: Array<{
+      name: string;
+      status: string;
+      use: string;
+    }>;
+  };
+  groups: Array<{
+    group: string;
+    purpose: string;
+    records: Array<{
+      name: string;
+      summary: string;
+    }>;
+  }>;
+  concepts: Array<{
+    name: string;
+    summary: string;
+  }>;
+};
+
+type RolesDoc = BaseDocPage & {
+  page: "roles";
+  roles: Array<{
+    name: string;
+    responsibility: string;
+  }>;
+};
+
+export type GlossaryTerm = {
+  term: string;
+  category: string;
+  definition: string;
+};
+
+type GlossaryDoc = BaseDocPage & {
+  page: "glossary";
+  terms: GlossaryTerm[];
+};
+
+export type DocPage = StartHereDoc | OutcomesDoc | FlowDoc | RecordsDoc | RolesDoc | GlossaryDoc;
+
+export const DOC_REFERENCE: Record<DocPageId, DocPage> = {
+  start_here: {
+    page: "start_here",
+    title: "DX Complete",
+    sourceUrl: `${DOC_SOURCE_BASE_URL}/index.html`,
+    summary:
+      "A practical way to decide what is worth doing, deliver it with control, run it safely, and learn from the results.",
+    phases: [
+      {
+        number: "01",
+        name: "Orient",
+        description: "Capture the desired outcome, restate expectations, and confirm how success will be recognized."
+      },
+      {
+        number: "02",
+        name: "Elicit",
+        description: "Turn expectations into requirements, dependencies, unknowns, and risk."
+      },
+      {
+        number: "03",
+        name: "Weigh",
+        description: "Compare expected cost, expected value, risks, and confidence before recording a Commitment or Deferral."
+      },
+      {
+        number: "04",
+        name: "Build",
+        description: "Turn committed requirements into working changes."
+      },
+      {
+        number: "05",
+        name: "Go Live",
+        description: "Prepare the change, confirm readiness, and put it into use."
+      },
+      {
+        number: "06",
+        name: "Operate",
+        description: "Run the service, help users, and respond when something goes wrong."
+      },
+      {
+        number: "07",
+        name: "Measure",
+        description: "Compare expected and actual cost or benefit when data is available."
+      }
+    ]
+  },
+  outcomes: {
+    page: "outcomes",
+    title: "Why DX Complete exists",
+    sourceUrl: `${DOC_SOURCE_BASE_URL}/outcomes.html`,
+    summary:
+      "DX Complete gives teams a shared way to decide what is worth doing, control how it changes, run it safely, and learn from the result.",
+    outcomes: [
+      {
+        name: "Consistent operation",
+        description: "Teams use the same phases, records, roles, and handoffs to manage work and service signals."
+      },
+      {
+        name: "Clearer decisions",
+        description: "Goals, requirements, estimates, risks, and decisions stay connected."
+      },
+      {
+        name: "Budget clarity",
+        description: "Current cost is attempted, future cost is estimated, and actual cost is captured when available."
+      },
+      {
+        name: "Controlled change",
+        description: "Expectations, requirements, tasks, checks, changes, releases, and deployments can be followed."
+      },
+      {
+        name: "Review and compliance support",
+        description: "Important decisions, checks, approvals, releases, and measurements have a place to be recorded."
+      },
+      {
+        name: "Measured improvement",
+        description: "Measured results can improve future assumptions about cost, value, risk, and effort."
+      }
+    ],
+    transformationValue: [
+      {
+        state: "Before",
+        focus: "Current cost and friction",
+        description: "What the existing process, service, support load, risk, delay, or manual effort costs today."
+      },
+      {
+        state: "Planned",
+        focus: "Expected cost and value",
+        description: "What the proposed change is expected to cost and what improvement it is expected to create."
+      },
+      {
+        state: "After",
+        focus: "Measured improvement",
+        description: "What changed after launch, including actual cost and benefit when those signals are available."
+      }
+    ],
+    goodLooksLike: [
+      {
+        statement: "People know why work is happening.",
+        description: "The goal, problem, and requirement set are clear enough to discuss and decide."
+      },
+      {
+        statement: "Cost is visible enough to make a responsible choice.",
+        description: "Incomplete data is allowed, but unknowns and assumptions are visible."
+      },
+      {
+        statement: "Change is traceable from idea to operation.",
+        description:
+          "Records show how a request became requirements, tasks, checks, change history, release, deployment, and support history."
+      },
+      {
+        statement: "Service learning feeds future work.",
+        description: "User support signals, incidents, actual cost, and measured value can improve the next decision."
+      }
+    ]
+  },
+  flow: {
+    page: "flow",
+    title: "Flow",
+    sourceUrl: `${DOC_SOURCE_BASE_URL}/flow.html`,
+    summary:
+      "Flow explains each phase in detail: the main steps, the roles involved, the important choices, the records used, and the handoff to the next phase.",
+    phases: [
+      {
+        number: "01",
+        name: "Orient",
+        description: "Capture the desired outcome, restate expectations, and confirm how success will be recognized.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-orient.html`
+      },
+      {
+        number: "02",
+        name: "Elicit",
+        description: "Turn expectations into requirements, dependencies, unknowns, and risk.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-elicit.html`
+      },
+      {
+        number: "03",
+        name: "Weigh",
+        description: "Compare expected cost, expected value, risks, and confidence before recording a Commitment or Deferral.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-weigh.html`
+      },
+      {
+        number: "04",
+        name: "Build",
+        description: "Turn committed requirements into working changes.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-build.html`
+      },
+      {
+        number: "05",
+        name: "Go Live",
+        description: "Prepare the change, confirm readiness, and put it into use.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-go-live.html`
+      },
+      {
+        number: "06",
+        name: "Operate",
+        description: "Run the service, help users, and respond when something goes wrong.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-operate.html`
+      },
+      {
+        number: "07",
+        name: "Measure",
+        description: "Compare expected and actual cost or benefit when data is available.",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/phase-measure.html`
+      }
+    ]
+  },
+  records: {
+    page: "records",
+    title: "Records",
+    sourceUrl: `${DOC_SOURCE_BASE_URL}/objects.html`,
+    summary:
+      "Records are information DX Complete keeps so decisions, work, service issues, and measurements can be followed over time.",
+    routingGuidance: {
+      principle:
+        "Use the dedicated record first. Journal is the fallback for relevant context only when no dedicated record fits.",
+      sharpTest:
+        "Will anything reference or depend on this? If yes, prefer a dedicated record that can carry the relationship.",
+      axes: [
+        {
+          name: "Kind of information",
+          test: "Claims, goals, and success criteria go to Statement, Expectation, or Requirement; choices go to Decision; actions go to Task; events or controlled history go to matching records such as Change or Risk; otherwise relevant context may go to Journal."
+        },
+        {
+          name: "Process-bound or process-free",
+          test: "Statement, Expectation, Requirement, Decision, Task, Change, and Risk can advance work or carry dependencies. Journal is parallel context and does not advance the process by itself."
+        },
+        {
+          name: "Attachment",
+          test: "If another record will satisfy it, derive from it, be informed by it, or depend on it, use a dedicated record. If it is only useful background, Journal may fit."
+        }
+      ],
+      routingOrder: [
+        { signal: "Desired truth, success criteria, or buildable commitment", record: "Statement, Expectation, or Requirement" },
+        { signal: "Choice between alternatives", record: "Decision" },
+        { signal: "Action someone needs to do", record: "Task" },
+        { signal: "Event or controlled service/process history", record: "Change, Risk, or the matching event/history record" },
+        { signal: "Operational infrastructure state", record: "Operational Registry through Environment and Component records" },
+        { signal: "Relevant context with no better home", record: "Journal" }
+      ],
+      edgeCases: [
+        "A passing mention of a choice can stay in Journal; the choice itself, with rationale, should be a Decision.",
+        "A reminder may look like context, but if someone needs to act on it, it should be a Task.",
+        "A note that repeatedly informs decisions or work should be promoted from Journal to the appropriate dedicated record."
+      ],
+      promotion:
+        "Journal content that becomes load-bearing should be promoted to Statement, Expectation, Requirement, Decision, Task, Change, Risk, or another dedicated record, then linked back where useful.",
+      futureContainers: [
+        {
+          name: "Operational Registry",
+          status: "current",
+          use: "Environment and Component records keep operational inventory out of Journal."
+        }
+      ]
+    },
+    groups: [
+      {
+        group: "Scope",
+        purpose: "Set the need",
+        records: [
+          { name: "Workspace", summary: "The container for one service and the work connected to it." },
+          { name: "Statement", summary: "A person's own words before they are interpreted or translated, kept as a traceable record." },
+          {
+            name: "Journal",
+            summary: "Shared workspace notes for relevant background, preferences, observations, and context that has no dedicated record home."
+          },
+          {
+            name: "Environment",
+            summary: "A named operating context such as local, staging, or production."
+          },
+          {
+            name: "Component",
+            summary: "One environment-specific operational item, with kind, location details, identifiers, secret pointers, notes, and version history."
+          },
+          {
+            name: "Expectation",
+            summary: "The result a person or group expects, including how success will be recognized. Prior versions and review notes can be kept without blocking progress."
+          },
+          {
+            name: "Requirement",
+            summary: "A commitment to make something true in a buildable and checkable way. Prior versions and review notes can be kept without blocking progress."
+          }
+        ]
+      },
+      {
+        group: "Weigh",
+        purpose: "Decide whether to commit now or defer",
+        records: [
+          {
+            name: "Estimate",
+            summary: "An Engineer cost estimate for the scope being weighed, with itemized costs and roll-ups for one-time and recurring amounts."
+          },
+          {
+            name: "Benefits",
+            summary: "An Owner-authored view of expected benefits. Benefits may be quantified or qualitative."
+          },
+          { name: "Commitment", summary: "An Owner record that commits requirements or expectations into Build, with any reservations visible." },
+          { name: "Deferral", summary: "An Owner record for not committing yet, with conditions that make a future Commitment possible." },
+          { name: "Risk", summary: "Something uncertain that could affect value, delivery, service, or compliance." }
+        ]
+      },
+      {
+        group: "Work",
+        purpose: "Act on the work",
+        records: [
+          {
+            name: "Task",
+            summary: "Concrete work with an entry history; current status comes from the latest status-change entry."
+          },
+          {
+            name: "Change",
+            summary: "A record for a specific alteration to the running service, with plan sections and append-only event history."
+          }
+        ]
+      },
+      {
+        group: "Throughout",
+        purpose: "Decide and follow up",
+        records: [
+          {
+            name: "Decision",
+            summary: "A revisitable choice record with ordered entries and links to the records that informed it."
+          },
+          {
+            name: "DX Complete Ticket",
+            summary: "A private place to raise a question, report, request, correction, or follow-up with DX Complete."
+          }
+        ]
+      }
+    ],
+    concepts: [
+      {
+        name: "Constraints, dependencies, and unknowns",
+        summary: "Normally captured in requirements, risks, decisions, review notes, or task details."
+      },
+      {
+        name: "Verification and validation",
+        summary: "Checks and outcomes can be captured in task details, change history, decisions, or linked notes."
+      },
+      {
+        name: "Release, deployment, controls, and evidence",
+        summary: "Currently represented through Change events, risks, decisions, and supporting notes."
+      },
+      {
+        name: "Support, incidents, problems, and feedback",
+        summary: "Operational signals can be handled through tickets, risks, tasks, changes, decisions, or new requirements."
+      },
+      {
+        name: "Measurement and estimate refinement",
+        summary: "Actual cost or benefit observations can update estimates, benefits, risks, decisions, or future work."
+      }
+    ]
+  },
+  roles: {
+    page: "roles",
+    title: "Roles",
+    sourceUrl: `${DOC_SOURCE_BASE_URL}/roles.html`,
+    summary:
+      "Roles separate responsibility so decisions, building, quality checks, support, and service operation are not confused.",
+    roles: [
+      { name: "Owner", responsibility: "Sets priorities, defines outcomes and requirements, commits budget and scope, validates outcomes, and accepts risk when needed." },
+      { name: "Engineer", responsibility: "Turns committed requirements into tasks and working changes, either directly or by driving coding-capable tools." },
+      { name: "Tester", responsibility: "Checks completed work against requirements and success criteria." },
+      { name: "Operator", responsibility: "Releases, deploys, monitors, runs the service, and manages users, permissions, settings, provisioning, and run-side security." },
+      { name: "Support Agent", responsibility: "Helps users, captures signals, and routes questions, feedback, and issues to the right follow-up." },
+      {
+        name: "End User",
+        responsibility: "Uses the service and provides requests, feedback, corrections, and issue reports."
+      }
+    ]
+  },
+  glossary: {
+    page: "glossary",
+    title: "Glossary",
+    sourceUrl: `${DOC_SOURCE_BASE_URL}/glossary.html`,
+    summary: "Common DX Complete terms, written in plain language.",
+    terms: [
+      { term: "Approval", category: "Risk and decisions", definition: "A separate authority confirming an expectation or decision, tracked when it reduces risk." },
+      { term: "Benefit Item", category: "Cost and benefit", definition: "One item inside Benefits. It may have an amount or range, or it may be qualitative with no amount." },
+      { term: "Benefits", category: "Cost and benefit", definition: "An Owner-authored benefit record used during Weigh, linked to the requirements or expectations it covers. Benefits may be quantified or qualitative." },
+      { term: "Build", category: "Delivery", definition: "Turning committed requirements into tasks, working changes, and verification." },
+      { term: "Change", category: "Delivery", definition: "A service change record for a discrete alteration to the running service. It records the plan, execution, rollback, notice, veto, emergency posture, decision, result, and recovery history without enforcing the operation." },
+      { term: "Change Plan", category: "Delivery", definition: "The part of a Change record that explains what is changing, why, scope, timing, and notice." },
+      { term: "Checkpoint", category: "Risk and decisions", definition: "A confirmation point that reduces risk. It can be approved, formally accepted as risk by the Owner, or proceeded past with open risk visible." },
+      { term: "Codex", category: "Delivery", definition: "A coding-capable model that may assist the Engineer. Codex is not a role." },
+      { term: "Commitment", category: "Business context", definition: "An Owner record that says preparation is sufficient to commit requirements or expectations into Build, with any reservations kept visible." },
+      { term: "Complete Engineering", category: "Delivery", definition: "The delivery part of DX Complete: build, check, validate, and put the change into use." },
+      { term: "Component", category: "Run and support", definition: "One operational item in one Environment, such as an app, database, queue, storage location, or external service. It records where it lives and which non-secret identifiers or secret locations matter." },
+      { term: "Condition", category: "Business context", definition: "Something that must be addressed before a Deferral can resolve into a Commitment." },
+      { term: "Constraints", category: "Business context", definition: "Limits that affect the work, such as time, access, policy, budget, or risk." },
+      { term: "Control", category: "Risk and decisions", definition: "A rule, check, or approval used to reduce risk." },
+      { term: "Decision", category: "Risk and decisions", definition: "A revisitable choice record. The current decision comes from the latest decision entry, while earlier arguments, notes, and decisions remain visible." },
+      { term: "Decision Entry", category: "Risk and decisions", definition: "One ordered entry in a Decision, such as an argument, note, or decision. Later decision entries can supersede earlier ones without deleting them." },
+      { term: "Decision Input", category: "Risk and decisions", definition: "A record that informed a decision. Outgoing links from a decision show what informed it; incoming links to a record show which decisions used it." },
+      { term: "Deferral", category: "Business context", definition: "An Owner record for not committing yet, with explicit conditions that make the path to a future Commitment clear." },
+      { term: "Dependencies", category: "Business context", definition: "People, systems, data, or decisions the work depends on." },
+      { term: "Deployment", category: "Delivery", definition: "Putting a release or change into use." },
+      { term: "DX Complete Ticket", category: "Business context", definition: "A private item used to raise a question, report, request, correction, or follow-up with DX Complete." },
+      { term: "Elicit", category: "Business context", definition: "Turning expectations into requirements, dependencies, unknowns, and risk before estimating the work." },
+      { term: "Emergency Change", category: "Delivery", definition: "A change where normal notice is shortened or skipped because both importance and immediacy are recorded." },
+      { term: "End User", category: "Role", definition: "The person the service is for; uses the service and provides requests, feedback, corrections, and issue reports." },
+      { term: "Engineer", category: "Role", definition: "The role that turns committed requirements into tasks and working changes, either directly or by driving coding-capable tools." },
+      { term: "Environment", category: "Run and support", definition: "A named operating context such as local, staging, or production. Components belong to one Environment so each operating context can be understood separately." },
+      { term: "Estimate", category: "Cost and benefit", definition: "An Engineer cost estimate used during Weigh, with itemized cost line items linked to the requirements or expectations it covers." },
+      { term: "Estimate Line Item", category: "Cost and benefit", definition: "One cost item inside an Estimate, with a label, amount or range, one-time or recurring timing, and currency." },
+      { term: "Estimate Refinement", category: "Cost and benefit", definition: "Using real results to improve future cost and benefit estimates." },
+      { term: "Evidence", category: "Risk and decisions", definition: "Information that supports a decision, check, release, or measurement." },
+      { term: "Execution Plan", category: "Delivery", definition: "The ordered practical steps inside a Change record for carrying out the change." },
+      { term: "Expectation", category: "Business context", definition: "The result a person or group expects, including how success will be recognized, with approval tracked where needed." },
+      { term: "Feedback", category: "Run and support", definition: "A signal from a user, support interaction, service issue, or observed result." },
+      { term: "Go Live", category: "Delivery", definition: "Putting a change into use after readiness is confirmed." },
+      { term: "Greenfield", category: "Business context", definition: "Work that starts from a new idea rather than an existing service." },
+      { term: "Handoff", category: "Delivery", definition: "The point where a phase has enough clarity to move into the next phase." },
+      { term: "Incident", category: "Run and support", definition: "An event that affects, or may affect, the service and needs a response." },
+      { term: "Informed By", category: "Risk and decisions", definition: "The relationship from a decision to the record that helped inform it." },
+      { term: "Journal", category: "Business context", definition: "A shared workspace record for relevant notes that do not have a better dedicated home. Journal entries are append-only and visible to workspace members." },
+      { term: "Journal Note", category: "Business context", definition: "A raw Journal entry with body text, author, and timestamp. It can be summarized later without being deleted." },
+      { term: "Journal Summary", category: "Business context", definition: "A compact Journal entry that summarizes covered notes and points back to them so older detail remains retrievable." },
+      { term: "Limited Disclosure", category: "Business context", definition: "A situation where some information is unavailable or cannot be shared." },
+      { term: "Locator", category: "Run and support", definition: "Structured location information for a Component, such as a URL, project, region, host, or route." },
+      { term: "Measure", category: "Cost and benefit", definition: "Compare expected and actual cost or benefit when data is available." },
+      { term: "Measurement", category: "Cost and benefit", definition: "Comparing expected and actual cost or benefit when data is available." },
+      { term: "Operate", category: "Run and support", definition: "Run the service, support users, and respond to issues." },
+      { term: "Operational Registry", category: "Run and support", definition: "The inventory of Environments and Components that shows what exists, where it lives, and which secret locations are relevant. It is not monitoring, diagnostics, a secret vault, an event log, or a runbook." },
+      { term: "Operator", category: "Role", definition: "The role that releases, deploys, monitors, runs the service, and manages users, permissions, settings, provisioning, and run-side security." },
+      { term: "Outcome", category: "Business context", definition: "The result the work is meant to create or improve." },
+      { term: "Owner", category: "Role", definition: "The role that sets authority, priority, outcome direction, requirements, product validation direction, budget commitment, escalation direction, and formal risk acceptance." },
+      { term: "Problem", category: "Run and support", definition: "An underlying or repeated issue that may need deeper improvement work." },
+      { term: "Proceeding Past an Open Checkpoint", category: "Risk and decisions", definition: "Moving forward while an approval, readiness concern, or other checkpoint is still open. The risk remains visible and is not formally accepted." },
+      { term: "Product Validation", category: "Delivery", definition: "Confirming that the completed work achieves the intended outcome." },
+      { term: "QA Verification", category: "Delivery", definition: "Checking that completed work meets the requirements and success criteria." },
+      { term: "Readiness Checks", category: "Delivery", definition: "The checks used before Go Live to confirm that a change is prepared, supportable, and safe enough to put into use." },
+      { term: "Record", category: "Business context", definition: "Information kept so decisions, work, service issues, and measurements can be followed over time." },
+      { term: "Record Link", category: "Business context", definition: "A relationship from one record to another. Links can be added or removed when the relationship changes or was recorded incorrectly." },
+      { term: "Readable ID", category: "Business context", definition: "A short record reference such as REQ-0001. It helps people refer to records while the UUID remains the primary key." },
+      { term: "Release", category: "Delivery", definition: "A set of changes prepared to be put into use." },
+      { term: "Requirement", category: "Delivery", definition: "A commitment to make something true in a buildable and checkable way." },
+      { term: "Requirement Detail", category: "Delivery", definition: "Optional behavior, edge cases, or check notes kept with a requirement." },
+      { term: "Requirement Set", category: "Business context", definition: "The group of requirements being estimated, committed, built, or stopped together." },
+      { term: "Reservation", category: "Business context", definition: "A concern recorded inside a Commitment when the Owner moves forward despite it." },
+      { term: "Review Note", category: "Delivery", definition: "A free-text note on an expectation or requirement. It may be marked important, but it does not block progress or require an Owner response." },
+      { term: "Risk", category: "Risk and decisions", definition: "Something uncertain that could affect value, delivery, service, or compliance." },
+      { term: "Risk Acceptance", category: "Risk and decisions", definition: "An Owner decision to own an open risk on the project's behalf. It is different from simply proceeding past an open checkpoint." },
+      { term: "Rollback Plan", category: "Delivery", definition: "The part of a Change record that explains how to reverse or recover if the change fails or should not remain in use." },
+      { term: "Roll-up", category: "Cost and benefit", definition: "Grouped totals from quantified cost or benefit items, keeping one-time amounts, recurring amounts, periods, and currencies distinct." },
+      { term: "Secret Pointer", category: "Run and support", definition: "A reference to where a secret is stored and what it is called. It should not contain the secret value." },
+      { term: "Statement", category: "Business context", definition: "A person's own words before they are interpreted or translated, kept as the traceable root for expectations and downstream work." },
+      { term: "Success Criteria", category: "Delivery", definition: "The conditions used to decide whether completed work satisfies the need." },
+      { term: "Support Agent", category: "Role", definition: "The role that helps users, captures signals, and routes questions, feedback, and issues to the right follow-up." },
+      { term: "Support Ticket", category: "Run and support", definition: "A user request, question, or issue report." },
+      { term: "Task", category: "Delivery", definition: "A piece of work with an entry history. The current status comes from the latest status-change entry." },
+      { term: "Task Entry", category: "Delivery", definition: "One ordered entry in a Task, such as a comment, note, or status change." },
+      { term: "Tester", category: "Role", definition: "The role that checks completed work against requirements and success criteria." },
+      { term: "Transformation", category: "Business context", definition: "Improving an existing service or way of working." },
+      { term: "Unknowns", category: "Business context", definition: "Important questions that are not answered yet." },
+      { term: "Veto", category: "Risk and decisions", definition: "A serious recorded objection to a Change by the Owner or Engineer. It does not mechanically stop the Operator, but proceeding over it creates a strong accountability record." },
+      { term: "Version History", category: "Risk and decisions", definition: "Prior versions kept when an expectation or requirement changes, so the current wording can be understood without losing what came before." },
+      { term: "Weigh", category: "Business context", definition: "The phase where cost, value, risk, and confidence are compared before recording a Commitment or Deferral." },
+      { term: "Workspace", category: "Business context", definition: "The container for one service and the work connected to it." }
+    ]
+  }
+};
+
+export function getDocReference(page: DocPageId, term?: string): DocPage | (BaseDocPage & { term: GlossaryTerm }) {
+  const doc = DOC_REFERENCE[page];
+
+  if (term && page !== "glossary") {
+    throw new Error("The term parameter is only valid when page is glossary.");
+  }
+
+  if (page !== "glossary" || !term) {
+    return doc;
+  }
+
+  const normalizedTerm = normalizeTerm(term);
+  const glossaryDoc = doc as GlossaryDoc;
+  const glossaryTerm = glossaryDoc.terms.find((entry) => normalizeTerm(entry.term) === normalizedTerm);
+
+  if (!glossaryTerm) {
+    throw new Error(`Glossary term not found: ${term}`);
+  }
+
+  return {
+    page: glossaryDoc.page,
+    title: glossaryDoc.title,
+    sourceUrl: glossaryDoc.sourceUrl,
+    summary: glossaryDoc.summary,
+    term: glossaryTerm
+  };
+}
+
+function normalizeTerm(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, " ");
+}