dxcomplete 0.1.0 → 0.2.0

package/README.md

@@ -1,19 +1,23 @@
 # DX Complete
 
-DX Complete is an exploratory npm package for installing a reusable documentation, process, and MCP route kit into a Next.js workspace project.
+DX Complete installs a process, documentation, and MCP route scaffold into a Next.js workspace so a service can track decisions, requirements, tasks, changes, incidents, support, operations, and measurement over time.
 
-The broader product premise is:
-
-```text
-DX Complete = Decision Basis + Complete Engineering + Operations Measurement
-```
+## Quick Start
 
-The target command is:
+Install the scaffold into the current Next.js project:
 
 ```sh
 npx dxcomplete init
 ```
 
+The command creates editable DX Complete documentation and process files under `dxcomplete/`, installs Next.js route wrappers under `pages/api/`, writes `vercel.json` compatibility settings, and creates `dxcomplete/workspace.json` as the workspace identity for that service.
+
+The broader product premise is:
+
+```text
+DX Complete = Decision Basis + Complete Engineering + Operations Measurement
+```
+
 The scaffold is intended to help a team describe and revise a full engineering and service lifecycle model. It deliberately does not present the current model as decided. Roles, workflows, object taxonomy, and diagrams are draft material that should be edited as the operating model becomes clearer.
 
 ## Product Outcome
@@ -41,11 +45,11 @@ The working hypothesis is that DX Complete describes a full decision-basis, engi
 
 The current role model includes Owner, Engineer, Tester, Operator, Support Agent, and End User. The model keeps outcome authority, requirements, product validation, and risk acceptance visible inside Owner; implementation responsibilities inside Engineer; and administration responsibilities inside Operator.
 
-Current draft concepts include Workspace, Statement, Expectation, Requirement, Commitment, Deferral, Task, Environment, Component, Estimate, Benefits, Feedback, AuthoritativeRequest, FeatureRequest, Change, Incident, Problem, SupportTicket, Release, Deployment, Decision, Risk, and Control. These are represented in editable YAML and Markdown so they can evolve.
+Current runtime records include Workspace, Statement, Journal, Environment, Component, Maintenance Schedule, Expectation, Requirement, Estimate, Benefits, Value Realization, Commitment, Deferral, Task, Change, Incident, Problem, Support Request, Decision, Risk, and DX Complete Ticket. Other lifecycle concepts such as Feedback, Feature Request, Release, Deployment, Control, and Evidence remain useful language but are not all current records. They are represented in editable YAML and Markdown so the model can evolve deliberately.
 
 ## Usage
 
-Install the scaffold into the current Next.js project:
+Install into the current Next.js project:
 
 ```sh
 npx dxcomplete init
@@ -83,6 +87,8 @@ npx dxcomplete validate
 
 By default, the scaffold is written to `dxcomplete/` and a placeholder workflow is written to `.github/workflows/dxcomplete.yml`. Existing files are not overwritten unless `--force` is provided.
 
+If the target project does not already have a root `AGENTS.md`, `dxcomplete init` also writes a small Codex guidance file that points future engineering agents to `dxcomplete/docs/operating-guide.md` and `dxcomplete/docs/codex-integration.md`. If a root `AGENTS.md` already exists, it is skipped. `dxcomplete upgrade` does not overwrite a user-owned `AGENTS.md`.
+
 `dxcomplete upgrade` previews by default. It manages the installed route wrappers, Vercel compatibility configuration, and `dxcomplete/.install-manifest.json`. It does not overwrite `dxcomplete/workspace.json`. It reports drift in `dxcomplete/docs` and `dxcomplete/process` because those files are expected to become user-owned after installation.
 Run `dxcomplete init` before `dxcomplete upgrade`; upgrade refuses targets that do not already have `dxcomplete/workspace.json`.
 
@@ -150,7 +156,7 @@ Useful MCP tools for dogfooding include:
 
 - `runtime_status` to confirm the connected server process and MCP surface fingerprint.
 - `get_process_guide` to give MCP clients the current phase guide: Orient, Elicit, Weigh, Build, Go Live, Operate, and Measure.
-- `get_doc` to retrieve richer reference content for outcomes, flow, records, roles, and glossary terms on demand.
+- `get_doc` to retrieve richer reference content for outcomes, flow, records, roles, operating guidance, and glossary terms on demand.
 - `create_dxcomplete_ticket`, `append_dxcomplete_ticket`, `list_dxcomplete_tickets`, and `archive_dxcomplete_ticket` for private, appendable DX Complete Tickets from the current actor.
 - `list_unread_dxcomplete_ticket_replies` to see which tickets have unread DX Complete replies without returning the reply body, and `read_dxcomplete_ticket` to open a ticket and mark those replies read.
 - `append_journal_note`, `read_journal`, `get_journal_entry`, and `append_journal_summary` for shared workspace context that has no dedicated record home.
@@ -183,6 +189,8 @@ A DX Complete Ticket is the private place for an MCP client user to raise a ques
 
 The Journal is shared workspace context, not a private ticket. It is for useful notes that do not already belong in a dedicated record such as Statement, Expectation, Requirement, Decision, Risk, Change, or Task. The routing test is: will another record reference or depend on this? If yes, prefer a dedicated record. Journal content that becomes load-bearing should be promoted to the appropriate record and linked back where useful. Journal entries are append-only and can be linked as decision inputs or provenance. The default journal read returns the hot tier: active summaries plus active raw notes. Summary entries point back to covered raw notes, and covered notes are archived out of the hot read without being deleted.
 
+The Operating Guide explains record routing by role. Engineer/Codex work defaults to Requirement -> Task. Tester evidence usually belongs in Task entries, review notes, Risk, Decision, or Journal. Operator work uses Change for run-side alterations, Incident for specific service-impacting occurrences, Problem for underlying or recurring causes, and Environment or Component for operational inventory. Support Agent work starts with DX Complete Ticket, then promotes to shared records only when needed.
+
 For dogfood maintenance work that needs direct database access, batch the work in one process instead of running repeated one-off Mongo commands:
 
 ```sh

package/dist/init.js

@@ -18,6 +18,7 @@ export async function initProject(options) {
     await copyDirectory(path.join(packageRoot, "docs"), path.join(targetDir, "dxcomplete", "docs"), { force, dryRun }, result);
     await copyDirectory(path.join(packageRoot, "templates", "process"), path.join(targetDir, "dxcomplete", "process"), { force, dryRun }, result);
     await writeWorkspaceConfig(targetDir, { force, dryRun }, result);
+    await copyFileIfAbsent(path.join(packageRoot, "templates", "AGENTS.md"), path.join(targetDir, "AGENTS.md"), { dryRun }, result);
     await copyDirectory(path.join(packageRoot, "templates", "next", "pages"), path.join(targetDir, "pages"), { force, dryRun }, result);
     await copyFileIfAvailable(path.join(packageRoot, "templates", "next", "vercel.json"), path.join(targetDir, "vercel.json"), { force, dryRun }, result);
     if (includeGithubWorkflow) {
@@ -59,6 +60,24 @@ async function copyFileIfAvailable(sourcePath, destinationPath, options, result)
     await copyFile(sourcePath, destinationPath);
     result.written.push(relativeDestination);
 }
+async function copyFileIfAbsent(sourcePath, destinationPath, options, result) {
+    if (!(await fileExists(sourcePath))) {
+        return;
+    }
+    const relativeDestination = path.relative(result.targetDir, destinationPath);
+    const exists = await fileExists(destinationPath);
+    if (exists) {
+        result.skipped.push(relativeDestination);
+        return;
+    }
+    if (options.dryRun) {
+        result.planned.push(relativeDestination);
+        return;
+    }
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+    await copyFile(sourcePath, destinationPath);
+    result.written.push(relativeDestination);
+}
 async function writeWorkspaceConfig(targetDir, options, result) {
     const destinationPath = path.join(targetDir, "dxcomplete", "workspace.json");
     const relativeDestination = path.relative(result.targetDir, destinationPath);

package/dist/mcp/docs.d.ts

@@ -1,5 +1,5 @@
 export declare const DOC_SOURCE_BASE_URL = "https://dxcomplete.directeddomains.com";
-export declare const DOC_PAGE_IDS: readonly ["start_here", "outcomes", "flow", "records", "roles", "glossary"];
+export declare const DOC_PAGE_IDS: readonly ["start_here", "outcomes", "flow", "records", "roles", "operating_guide", "glossary"];
 export type DocPageId = (typeof DOC_PAGE_IDS)[number];
 type BaseDocPage = {
     page: DocPageId;
@@ -81,6 +81,22 @@ type RolesDoc = BaseDocPage & {
         responsibility: string;
     }>;
 };
+type OperatingGuideDoc = BaseDocPage & {
+    page: "operating_guide";
+    roles: Array<{
+        name: string;
+        use: string;
+        defaultRecords: string[];
+        avoid: string[];
+    }>;
+    recordRouting: Array<{
+        situation: string;
+        use: string;
+        why: string;
+    }>;
+    itsmBoundaries: string[];
+    freshAgentGuidance: string[];
+};
 export type GlossaryTerm = {
     term: string;
     category: string;
@@ -90,7 +106,7 @@ type GlossaryDoc = BaseDocPage & {
     page: "glossary";
     terms: GlossaryTerm[];
 };
-export type DocPage = StartHereDoc | OutcomesDoc | FlowDoc | RecordsDoc | RolesDoc | GlossaryDoc;
+export type DocPage = StartHereDoc | OutcomesDoc | FlowDoc | RecordsDoc | RolesDoc | OperatingGuideDoc | GlossaryDoc;
 export declare const DOC_REFERENCE: Record<DocPageId, DocPage>;
 export declare function getDocReference(page: DocPageId, term?: string): DocPage | (BaseDocPage & {
     term: GlossaryTerm;

package/dist/mcp/docs.js

@@ -1,5 +1,5 @@
 export const DOC_SOURCE_BASE_URL = "https://dxcomplete.directeddomains.com";
-export const DOC_PAGE_IDS = ["start_here", "outcomes", "flow", "records", "roles", "glossary"];
+export const DOC_PAGE_IDS = ["start_here", "outcomes", "flow", "records", "roles", "operating_guide", "glossary"];
 export const DOC_REFERENCE = {
     start_here: {
         page: "start_here",
@@ -172,11 +172,11 @@ export const DOC_REFERENCE = {
             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."
+                    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, Incident, Problem, Support Request, Maintenance Schedule, Value Realization, 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."
+                    test: "Statement, Expectation, Requirement, Decision, Task, Change, Incident, Problem, Support Request, Maintenance Schedule, Value Realization, and Risk can advance work or carry dependencies. Journal is parallel context and does not advance the process by itself."
                 },
                 {
                     name: "Attachment",
@@ -187,8 +187,15 @@ export const DOC_REFERENCE = {
                 { 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: "Run-side alteration to the service", record: "Change" },
+                { signal: "Specific service-impacting occurrence", record: "Incident" },
+                { signal: "Underlying or recurring cause behind incidents", record: "Problem" },
+                { signal: "User-facing question, request, or issue needing shared follow-up", record: "Support Request" },
+                { signal: "Uncertainty or exposure", record: "Risk" },
                 { signal: "Operational infrastructure state", record: "Operational Registry through Environment and Component records" },
+                { signal: "Recurring operational hygiene", record: "Maintenance Schedule" },
+                { signal: "Measured before/after value", record: "Value Realization" },
+                { signal: "Private question, report, request, correction, or follow-up with DX Complete", record: "DX Complete Ticket" },
                 { signal: "Relevant context with no better home", record: "Journal" }
             ],
             edgeCases: [
@@ -196,7 +203,7 @@ export const DOC_REFERENCE = {
                 "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.",
+            promotion: "Journal content that becomes load-bearing should be promoted to Statement, Expectation, Requirement, Decision, Task, Change, Incident, Problem, Support Request, Maintenance Schedule, Value Realization, Risk, or another dedicated record, then linked back where useful.",
             futureContainers: [
                 {
                     name: "Operational Registry",
@@ -224,6 +231,10 @@ export const DOC_REFERENCE = {
                         name: "Component",
                         summary: "One environment-specific operational item, with kind, location details, identifiers, secret pointers, notes, and version history."
                     },
+                    {
+                        name: "Maintenance Schedule",
+                        summary: "Recurring operational hygiene, with cadence, start date, rationale, version history, and due state derived from linked completed Changes or Tasks."
+                    },
                     {
                         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."
@@ -246,6 +257,10 @@ export const DOC_REFERENCE = {
                         name: "Benefits",
                         summary: "An Owner-authored view of expected benefits. Benefits may be quantified or qualitative."
                     },
+                    {
+                        name: "Value Realization",
+                        summary: "Measured before/after value tied to expectations, requirements, or commitments, with derived comparisons for each metric."
+                    },
                     { 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." }
@@ -261,7 +276,19 @@ export const DOC_REFERENCE = {
                     },
                     {
                         name: "Change",
-                        summary: "A record for a specific alteration to the running service, with plan sections and append-only event history."
+                        summary: "A record for a specific alteration to the running service, with change type, plan sections, risk and impact including downstream impact where known, append-only event history, and optional Git commit references on result or recovery events."
+                    },
+                    {
+                        name: "Incident",
+                        summary: "A record for a specific service-impacting or potentially service-impacting occurrence, with status and severity derived from entries."
+                    },
+                    {
+                        name: "Problem",
+                        summary: "A record for an underlying or recurring cause evidenced by one or more Incidents, with root cause and status derived from entries."
+                    },
+                    {
+                        name: "Support Request",
+                        summary: "A shared support ledger for a reported user experience, question, request, or issue, with current status derived from entries."
                     }
                 ]
             },
@@ -295,7 +322,7 @@ export const DOC_REFERENCE = {
             },
             {
                 name: "Support, incidents, problems, and feedback",
-                summary: "Operational signals can be handled through tickets, risks, tasks, changes, decisions, or new requirements."
+                summary: "Operational signals can be handled through tickets, incidents, problems, risks, tasks, changes, decisions, or new requirements. Use Incident for a specific occurrence and Problem for an underlying or recurring cause."
             },
             {
                 name: "Measurement and estimate refinement",
@@ -320,6 +347,151 @@ export const DOC_REFERENCE = {
             }
         ]
     },
+    operating_guide: {
+        page: "operating_guide",
+        title: "Operating Guide",
+        sourceUrl: `${DOC_SOURCE_BASE_URL}/operating-guide.html`,
+        summary: "How each role uses DX Complete in day-to-day work, including record routing and ITSM boundaries.",
+        roles: [
+            {
+                name: "Owner",
+                use: "Uses DX Complete to set direction, approve expectations when needed, weigh cost and benefit, record Commitment or Deferral, make Decisions, and formally accept risk when the project should own it.",
+                defaultRecords: ["Statement", "Expectation", "Benefits", "Value Realization", "Commitment", "Deferral", "Decision", "Risk"],
+                avoid: [
+                    "Do not turn every comment into a requirement.",
+                    "Do not use approval language for End User feedback.",
+                    "Do not hide reservations or low-confidence decisions."
+                ]
+            },
+            {
+                name: "Engineer and Codex assistance",
+                use: "Uses Requirement to Task as the normal build path. Codex may assist the Engineer, but Codex is a coding-capable tool, not a role.",
+                defaultRecords: ["Requirement", "Task", "Decision", "Risk", "Journal"],
+                avoid: [
+                    "Do not create a Change just because implementation work is happening.",
+                    "Do not use Journal when a Task, Decision, Risk, or Requirement is the real record.",
+                    "Do not invent Owner intent or End User feedback."
+                ]
+            },
+            {
+                name: "Tester",
+                use: "Uses DX Complete to keep verification tied to requirements and visible evidence. Verification can be captured through Task entries, review notes, Risk, Decision, or Journal depending on what is being learned.",
+                defaultRecords: ["Task", "Requirement", "Risk", "Decision", "Journal"],
+                avoid: [
+                    "Do not default to Change for testing observations.",
+                    "Do not treat a failed check as a new requirement unless the expected truth changed.",
+                    "Do not hide verification uncertainty in free text when it is a Risk."
+                ]
+            },
+            {
+                name: "Operator and administration",
+                use: "Uses DX Complete to keep run-side state, service changes, incidents, problems, and operational inventory legible, including Environments, Components, rollout or rollback plans, user permissions, and operational security.",
+                defaultRecords: ["Change", "Incident", "Problem", "Environment", "Component", "Maintenance Schedule", "Risk", "Decision"],
+                avoid: [
+                    "Do not paste secret values into records.",
+                    "Do not use Change for ordinary build work before it alters the running service.",
+                    "Do not create Incident or Problem merely because work is happening; use them only for operational signal or service-history meaning."
+                ]
+            },
+            {
+                name: "Support Agent",
+                use: "Uses DX Complete Ticket as the first stop for user questions, reports, requests, corrections, and follow-ups, then promotes shared follow-up only when needed.",
+                defaultRecords: ["Support Request", "DX Complete Ticket", "Statement", "Task", "Incident", "Problem", "Risk", "Decision", "Change", "Journal"],
+                avoid: [
+                    "Do not promote every ticket into shared process work.",
+                    "Do not use DX Complete Ticket for shared support follow-up when Support Request is the better record.",
+                    "Do not call a user signal an approval.",
+                    "Do not create ITSM-style records merely because a user reported something; promote only when the signal has operational or shared follow-up meaning."
+                ]
+            },
+            {
+                name: "End User",
+                use: "Uses the service and provides input. Another role captures that input as a Statement, report, request, correction, feedback signal, or ticket when it needs to enter DX Complete.",
+                defaultRecords: ["Statement", "DX Complete Ticket"],
+                avoid: [
+                    "Do not treat the End User as a DX Complete operator.",
+                    "Do not treat End User feedback as authority approval.",
+                    "Do not expect the End User to choose process records."
+                ]
+            }
+        ],
+        recordRouting: [
+            {
+                situation: "Normal implementation work",
+                use: "Task",
+                why: "A Task is the default record for concrete work someone needs to do."
+            },
+            {
+                situation: "Meaningful choice between alternatives",
+                use: "Decision",
+                why: "A Decision preserves what was chosen and which records informed it."
+            },
+            {
+                situation: "Uncertainty, exposure, or possible harm",
+                use: "Risk",
+                why: "A Risk keeps the uncertainty visible without pretending it is resolved."
+            },
+            {
+                situation: "Discrete alteration to the running service",
+                use: "Change",
+                why: "A Change is the current ITSM-style run-side control record."
+            },
+            {
+                situation: "Specific service-impacting occurrence",
+                use: "Incident",
+                why: "An Incident keeps response history for one occurrence visible."
+            },
+            {
+                situation: "Underlying or recurring cause behind one or more incidents",
+                use: "Problem",
+                why: "A Problem keeps investigation and root-cause history separate from the individual incidents it explains."
+            },
+            {
+                situation: "User-facing support follow-up",
+                use: "Support Request",
+                why: "A Support Request keeps the shared support thread visible without turning every report into an Incident."
+            },
+            {
+                situation: "Operational inventory",
+                use: "Environment or Component",
+                why: "The Operational Registry shows what exists and where it lives."
+            },
+            {
+                situation: "Recurring operational hygiene",
+                use: "Maintenance Schedule",
+                why: "A Maintenance Schedule keeps cadence and due state visible while completed Changes or Tasks show what happened."
+            },
+            {
+                situation: "Measured value after work or operation",
+                use: "Value Realization",
+                why: "Value Realization compares baseline and actual metrics without replacing Benefits or Estimates."
+            },
+            {
+                situation: "Useful context with no better dedicated home",
+                use: "Journal",
+                why: "Journal is fallback context, not the default home for load-bearing records."
+            },
+            {
+                situation: "Question, report, request, correction, or follow-up with DX Complete",
+                use: "DX Complete Ticket",
+                why: "A ticket is private to the submitting actor until someone promotes shared follow-up."
+            }
+        ],
+        itsmBoundaries: [
+            "Change is the current first-class run-side control record. Its risk and impact section should include downstream impact where known: what else may be affected and what depends on what is changing.",
+            "Result and recovery events on a Change may include optional Git commit references for the specific execution attempt or rollback. They are recorded as references only; DX Complete does not validate Git commits or assume a Git host.",
+            "Incident is the current first-class record for a specific service-impacting or potentially service-impacting occurrence.",
+            "Problem is the current first-class record for an underlying or recurring cause evidenced by one or more incidents.",
+            "Do not create ITSM-style records merely because work is happening; use them when the information is truly run-side control, operational signal, or service history."
+        ],
+        freshAgentGuidance: [
+            "Start by identifying the role being helped and the record that best matches the information.",
+            "For Engineer/Codex work, default to Requirement -> Task unless a Decision, Risk, Journal note, or Change is specifically warranted.",
+            "For Operator work, use Change only for run-side alteration and Environment or Component for operational inventory.",
+            "For Support Agent work, start with DX Complete Ticket before promoting into shared records.",
+            "When unsure, ask whether another record will reference or depend on the information. If yes, use the dedicated record."
+        ]
+    },
     glossary: {
         page: "glossary",
         title: "Glossary",
@@ -330,8 +502,10 @@ export const DOC_REFERENCE = {
             { 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: "Cadence", category: "Run and support", definition: "How often recurring operational work is expected to happen, such as every month or every quarter." },
+            { term: "Change", category: "Delivery", definition: "A service change record for a discrete alteration to the running service. It records the change type, plan, execution, rollback, notice, veto, decision, result, recovery history, and optional Git commit references 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: "Change Type", category: "Delivery", definition: "The classification of a Change as standard, normal, or emergency. It affects scrutiny and communication but does not enforce the operation." },
             { 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." },
@@ -348,7 +522,7 @@ export const DOC_REFERENCE = {
             { 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: "Emergency Change", category: "Delivery", definition: "A Change where normal notice or review is shortened because the situation is important and immediate. Missing rationale remains visible but does not block the record." },
             { 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." },
@@ -359,24 +533,31 @@ export const DOC_REFERENCE = {
             { 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: "Git Commit Reference", category: "Delivery", definition: "An optional commit identifier recorded on a Change result or recovery event to show what code state was used for that execution attempt or rollback. DX Complete records the reference as provided and does not validate it." },
             { 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: "Incident", category: "Run and support", definition: "A specific service-impacting or potentially service-impacting occurrence with response history, current status, and severity derived from ordered entries." },
+            { term: "Incident Entry", category: "Run and support", definition: "One ordered entry in an Incident, such as detected, update, severity, resolved, reopened, or note." },
             { 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: "Known Error", category: "Run and support", definition: "A Problem state showing an underlying cause is known even if the full improvement is not complete." },
             { 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: "Maintenance Schedule", category: "Run and support", definition: "A recurring operational hygiene record with cadence, start date, rationale, and due state derived from linked completed Changes or Tasks." },
             { term: "Measure", category: "Cost and benefit", definition: "Compare expected and actual cost or benefit when data is available." },
+            { term: "Measured At", category: "Cost and benefit", definition: "The date or time when a value metric baseline or actual value was measured." },
             { term: "Measurement", category: "Cost and benefit", definition: "Comparing expected and actual cost or benefit when data is available." },
+            { term: "Normal Change", category: "Delivery", definition: "The default Change type for an assessed alteration to the running service. It may carry a minor, significant, or major impact grade." },
             { 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: "Problem", category: "Run and support", definition: "An underlying or recurring cause evidenced by one or more Incidents, with investigation, root-cause, known-error, and resolution history." },
+            { term: "Problem Entry", category: "Run and support", definition: "One ordered entry in a Problem, such as identified, investigation, root cause, known error, resolved, reopened, or note." },
             { 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." },
@@ -390,21 +571,28 @@ export const DOC_REFERENCE = {
             { 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", category: "Risk and decisions", definition: "Something uncertain that could affect value, delivery, service, compliance, or operations. Current risk state comes from ordered entries." },
             { 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: "Risk Entry", category: "Risk and decisions", definition: "One ordered entry in a Risk, such as identified, assessment, treatment, monitor note, closed, or reopened." },
+            { term: "Risk Treatment", category: "Risk and decisions", definition: "The chosen response to a Risk: accept, mitigate, transfer, or avoid. Formal acceptance is Owner-only." },
             { 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: "Root Cause", category: "Run and support", definition: "The underlying cause recorded in a Problem when investigation identifies why one or more incidents occurred." },
+            { term: "Standard Change", category: "Delivery", definition: "A low-risk, pre-understood, repeatable Change type for work that can use a lighter path while still preserving the record." },
             { 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: "Support Request", category: "Run and support", definition: "A shared support record for a reported user experience, question, request, or issue that needs workspace-visible follow-up." },
+            { term: "Support Request Entry", category: "Run and support", definition: "One ordered entry in a Support Request, such as raised, triage, update, escalated, resolved, reopened, or note." },
             { 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: "Value Metric", category: "Cost and benefit", definition: "One before/after measure inside Value Realization, with a baseline, optional actual value, unit, direction, and measured dates." },
+            { term: "Value Realization", category: "Cost and benefit", definition: "A record that compares baseline and actual value metrics after work or operation when measurement is available." },
             { 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." }