@everfur/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+export { COMMANDS, ExitCode, REASON_CODES, buildDiagnosisDocument, buildExplanationDocument, buildSandboxDocument, buildVerificationDocument, editDistance, failureOutcome, formatOutcome, isKnownReasonCode, matchCommand, nextActionFor2 as nextActionForErrorCode, nextActionFor as nextActionForReason, nextActionsFor, parseCapabilities, parseDiagnostics, parseIdentityMode, parseSessionMintLanguage, parseSuppliedFacts, projectSandboxCreate, renderDiagnosis, renderExplanation, renderPlan, renderSandboxCreate, renderVerification, runCli, suggestCodes } from './chunk-67H43MI6.js';
+export { ADMIN_TOKEN, API_PREFIX, BASE_URL_ENV_VAR, CLI_VERSION, CREDENTIAL_SPECS, DEFAULT_TIMEOUT_MS, EMPTY_REGISTRY, ERRORS_DOCUMENT_KEY, IDEMPOTENT_METHODS, MISSING_FACT_NAMES, PARTNER_KEY, PARTNER_SECRET_KEY, PLAN_DOCUMENT_KIND, PLAN_SCHEMA_VERSION, REDACTED, SCHEMAS, SESSION_TOKEN, TransportError, apiUrl, buildDecisionSpace, clampTimeout, createApiClient, createRecordingClock, describeFailure, detectProject, digestOfProjection, digestsEqual, entryFromRow, ephemeralCredential, errorCodeOf, failureDetails, fetchTransport, isCorrelatableRequestId, isIdempotent, loadDecisionSpace, loadErrorRegistry, missingFactsFor, nodeFileSystem, planIntegration, resolveContractPath, resolveCredential, resolveEndpoint, runVerification, systemClock, validateContractFile, validateContractPublicEnvelope, validateDiagnosisDocument, validateErrorExplanationDocument, validatePlanDocument, validateSandboxCreateDocument, validateVerificationDocument, verifyDigest, walkSingle, walkTree, withPrefix } from './chunk-KQZ6ZXL7.js';
+
+// src/fs/memory-fs.ts
+function createMemoryFileSystem(files) {
+  const table = new Map(Object.entries(files));
+  const directories = /* @__PURE__ */ new Set();
+  for (const path of table.keys()) {
+    const segments = path.split("/");
+    for (let index = 1; index < segments.length; index += 1) {
+      directories.add(segments.slice(0, index).join("/"));
+    }
+  }
+  return Object.freeze({
+    readFile: (path) => table.get(path) ?? null,
+    exists: (path) => table.has(path) || directories.has(path),
+    isDirectory: (path) => directories.has(path) && !table.has(path)
+  });
+}
+
+export { createMemoryFileSystem };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@everfur/cli",
+  "version": "0.1.0",
+  "description": "Everfur CLI: plan, verify, and diagnose an Everfur pet-health integration from the terminal.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "everfur": "./dist/everfur.js",
+    "everfur-mcp": "./dist/everfur-mcp.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "schema",
+    "contract"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./schema/plan.v1.schema.json": "./schema/plan.v1.schema.json",
+    "./schema/contract-public.v1.schema.json": "./schema/contract-public.v1.schema.json",
+    "./schema/diagnosis.v1.schema.json": "./schema/diagnosis.v1.schema.json",
+    "./schema/sandbox-create.v1.schema.json": "./schema/sandbox-create.v1.schema.json",
+    "./schema/verification.v1.schema.json": "./schema/verification.v1.schema.json",
+    "./schema/error-explanation.v1.schema.json": "./schema/error-explanation.v1.schema.json"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/strip-sourcemap-pragma.mjs",
+    "clean": "rm -rf dist coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "pretest:coverage": "npm run build",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "npm run build",
+    "notices": "node scripts/build-third-party-notices.mjs",
+    "notices:check": "node scripts/build-third-party-notices.mjs --check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "yaml": "2.9.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "@types/node": "^20.14.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "eslint": "^9.9.0",
+    "tsup": "^8.2.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Everfur-Health/everfur-cli.git"
+  },
+  "homepage": "https://github.com/Everfur-Health/everfur-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Everfur-Health/everfur-cli/issues"
+  },
+  "keywords": [
+    "everfur",
+    "pet-health",
+    "cli",
+    "mcp",
+    "sdk",
+    "veterinary"
+  ],
+  "author": "Everfur Health, Inc."
+}

package/schema/contract-public.v1.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://everfur.com/contracts/contract-public/v1",
+  "title": "Everfur contract-public projection envelope",
+  "description": "The ENVELOPE around a contract-public projection. This CLI owns the envelope and the digest rule; it deliberately does NOT own the shape of `projection`, which is produced by the contract lane. Validating the payload here would fork the definition and guarantee the two drift. `projection` is therefore required to be an object and is otherwise opaque, and the digest is what proves it arrived intact. When the contract lane publishes its own payload schema, add it as a $ref under projection and bump to v2 only if that tightening rejects a document v1 accepted.",
+  "type": "object",
+  "required": ["schemaVersion", "kind", "generatedAt", "digest", "projection"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "everfur.contract-public" },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 timestamp. Outside the digest input, so re-stamping a projection does not invalidate it."
+    },
+    "digest": {
+      "type": "object",
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": {
+          "const": "sha256",
+          "description": "Only sha256 is defined for v1. A new algorithm is an added enum member, which v1 permits."
+        },
+        "value": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "Lowercase hex sha256 over the RFC 8785 style canonical JSON of `projection` alone."
+        }
+      }
+    },
+    "projection": {
+      "type": "object",
+      "description": "Opaque to this CLI. Owned by the contract lane."
+    }
+  }
+}

package/schema/diagnosis.v1.schema.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://everfur.com/contracts/cli-diagnosis/v1",
+  "title": "Everfur CLI diagnosis document",
+  "description": "The committed output contract of `everfur diagnose --json`. Mirrors src/commands/diagnose/document.ts; tests/contract validates real emitted output against this file on every run so the two cannot drift. Compatibility rule for schemaVersion 1: fields and enum members may be ADDED; nothing is removed, renamed, retyped, or given a new meaning. reasonCode is deliberately NOT an enum: the platform's DiagnosticsReasonCode grows when a new decision point is added, and a CLI that rejected an unrecognised cause would fail exactly when something new broke. additionalProperties is left open for the same reason.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "kind",
+    "generatedBy",
+    "endpoint",
+    "requestId",
+    "evaluatedAt",
+    "client",
+    "auth",
+    "scope",
+    "summary",
+    "capabilities"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "everfur.diagnosis" },
+    "generatedBy": { "$ref": "#/$defs/GeneratedBy" },
+    "endpoint": {
+      "type": "object",
+      "required": ["baseUrl", "path"],
+      "properties": {
+        "baseUrl": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 }
+      }
+    },
+    "requestId": {
+      "description": "The X-Request-ID of the diagnosing call. Null only when the response carried none.",
+      "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 1 }]
+    },
+    "evaluatedAt": { "type": "string" },
+    "client": {
+      "type": "object",
+      "required": ["id", "slug"],
+      "properties": {
+        "id": { "type": "string" },
+        "slug": { "type": "string" }
+      }
+    },
+    "auth": {
+      "type": "object",
+      "required": [
+        "mode",
+        "anonymous",
+        "userRefPrefix",
+        "userRole",
+        "roleSource",
+        "sessionId",
+        "partnerKeyScopeResolved"
+      ],
+      "properties": {
+        "mode": { "type": "string" },
+        "anonymous": { "type": "boolean" },
+        "userRefPrefix": {
+          "description": "At most the first 8 characters of the resolved user ref. Never a credential.",
+          "type": "string",
+          "maxLength": 8
+        },
+        "userRole": { "type": "string" },
+        "roleSource": { "type": "string" },
+        "sessionId": { "type": "string" },
+        "partnerKeyScopeResolved": { "type": "boolean" }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "required": ["provisioned", "resolverStatus", "revision", "region", "levels"],
+      "properties": {
+        "provisioned": { "type": "boolean" },
+        "resolverStatus": { "type": "string" },
+        "revision": { "type": "integer", "minimum": 0 },
+        "region": { "type": "string" },
+        "levels": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["level", "kind", "present"],
+            "properties": {
+              "level": { "type": "integer", "minimum": 1, "maximum": 5 },
+              "kind": { "type": "string" },
+              "present": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["total", "available", "unavailable", "byReasonCode"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "available": { "type": "integer", "minimum": 0 },
+        "unavailable": { "type": "integer", "minimum": 0 },
+        "byReasonCode": {
+          "description": "Cause code to how many capabilities carry it. The field that turns eight symptoms into one ticket.",
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/CapabilityDiagnosis" }
+    }
+  },
+  "$defs": {
+    "GeneratedBy": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "CapabilityDiagnosis": {
+      "type": "object",
+      "required": [
+        "key",
+        "available",
+        "reasonCode",
+        "reason",
+        "entitlementReasonCode",
+        "decidedAtLevel",
+        "decidedAtKind",
+        "surface",
+        "nextAction"
+      ],
+      "properties": {
+        "key": { "type": "string", "minLength": 1 },
+        "available": { "type": "boolean" },
+        "reasonCode": {
+          "description": "The EFFECTIVE cause: the fence that blocks this key, so it names what has to be fixed first.",
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "description": "The server's own static copy for the code. Never operator or upstream text.",
+          "type": "string"
+        },
+        "entitlementReasonCode": {
+          "description": "What the entitlement lattice alone decided, ignoring runtime gates. Differs from reasonCode only when a gate masks a lattice outcome.",
+          "type": "string",
+          "minLength": 1
+        },
+        "decidedAtLevel": {
+          "oneOf": [{ "type": "null" }, { "type": "integer", "minimum": 1, "maximum": 5 }]
+        },
+        "decidedAtKind": { "oneOf": [{ "type": "null" }, { "type": "string" }] },
+        "surface": {
+          "description": "The runtime-gated surface name, disclosed only to a caller the lattice grants. Null otherwise.",
+          "oneOf": [{ "type": "null" }, { "type": "string" }]
+        },
+        "nextAction": {
+          "description": "CLI-authored. What the partner should do about this cause, which the server cannot know.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/schema/error-explanation.v1.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://everfur.com/contracts/cli-error-explanation/v1",
+  "title": "Everfur CLI error explanation document",
+  "description": "The committed output contract of `everfur explain-error <code> --json`. Every field except `nextAction` is read from the contract-public projection named in `source`, and `source.digest` is the sha256 that projection was verified against, so a reader can prove which registry an explanation came from. `nextAction` is CLI-authored and derived from retryable plus httpStatus, which is why a code added to the registry tomorrow already gets a correct action today.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "kind",
+    "generatedBy",
+    "code",
+    "source",
+    "envelope",
+    "httpStatus",
+    "namingFamily",
+    "retryable",
+    "confirmedOnWire",
+    "surfaces",
+    "cause",
+    "display",
+    "docUrl",
+    "nextAction"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "everfur.error-explanation" },
+    "generatedBy": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "code": {
+      "description": "Exactly the string the wire carries. Not normalised: three naming families are live at once and a client branches on the literal.",
+      "type": "string",
+      "minLength": 1
+    },
+    "source": {
+      "type": "object",
+      "required": ["path", "digest"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "envelope": { "type": "string", "minLength": 1 },
+    "httpStatus": { "type": "integer", "minimum": 0 },
+    "namingFamily": { "type": "string", "minLength": 1 },
+    "retryable": { "type": "boolean" },
+    "confirmedOnWire": {
+      "description": "False means the code exists in source but no live route was traced emitting it. Documentation, not a contract to branch on.",
+      "type": "boolean"
+    },
+    "surfaces": { "type": "array", "items": { "type": "string" } },
+    "cause": { "type": "string" },
+    "display": {
+      "description": "Safe copy a client may show a person as-is, authored by the contract lane.",
+      "type": "string"
+    },
+    "docUrl": { "type": "string" },
+    "nextAction": { "type": "string", "minLength": 1 }
+  }
+}

package/schema/plan.v1.schema.json

@@ -0,0 +1,244 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://everfur.com/contracts/cli-plan/v1",
+  "title": "Everfur CLI plan document",
+  "description": "The committed output contract of `everfur plan --json`. Mirrors the TypeScript type in src/commands/plan/types.ts; tests/contract validates real emitted output against this file on every run so the two cannot drift. Compatibility rule for schemaVersion 1: fields and enum members may be ADDED; nothing is removed, renamed, retyped, or given a new meaning. Any of those is schemaVersion 2 and a new schema file. `additionalProperties` is left open on objects for exactly that reason: a consumer pinned to v1 must not break when v1.x gains a field. When the planner decision trees landed, this file gained the `blocked`, `principles` and `decisionSpace` fields, two `missingFacts[].fact` members and one `status` member, all additive; and `Capability` and `IdentityMode` stopped being enums, because the set of capabilities is published by the platform contract rather than by this CLI, and an enum here would reject a capability the platform had already shipped. That relaxation accepts every document v1 accepted and rejects nothing it used to, which is the test that keeps it inside v1.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "kind",
+    "generatedBy",
+    "status",
+    "detected",
+    "supplied",
+    "missingFacts",
+    "steps",
+    "blocked",
+    "principles",
+    "warnings",
+    "decisionSpace"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "kind": { "const": "everfur.plan" },
+    "generatedBy": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "status": { "enum": ["ready", "underspecified", "blocked"] },
+    "detected": { "$ref": "#/$defs/Detection" },
+    "supplied": {
+      "type": "object",
+      "required": ["capabilities", "identityMode"],
+      "properties": {
+        "capabilities": {
+          "description": "null means the flag was absent. An empty array is never emitted.",
+          "oneOf": [
+            { "type": "null" },
+            { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/Capability" }, "uniqueItems": true }
+          ]
+        },
+        "identityMode": {
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/IdentityMode" }]
+        },
+        "sessionMintLanguage": {
+          "description": "The backend language that mints sessions. Non-null only when the identity mode requires a server-side mint.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/OptionId" }]
+        }
+      }
+    },
+    "missingFacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/MissingFact" }
+    },
+    "steps": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PlanStep" }
+    },
+    "blocked": {
+      "description": "Capabilities the caller asked for that the contract refuses, with the reason and where to ask. Present in every status; non-empty means no step below covers those capabilities.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/BlockedCapability" }
+    },
+    "principles": {
+      "description": "Guidance that holds regardless of what was answered, carried in the document so it survives the loss of the context that produced the plan.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/PlanPrinciple" }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/PlanWarning" }
+    },
+    "decisionSpace": {
+      "description": "Which contract projection produced this plan. Null only on the refusal that says none was found.",
+      "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/DecisionSpaceProvenance" }]
+    }
+  },
+  "allOf": [
+    {
+      "description": "status and missingFacts are two views of one fact and can never disagree.",
+      "if": { "properties": { "status": { "const": "underspecified" } }, "required": ["status"] },
+      "then": {
+        "properties": {
+          "missingFacts": { "minItems": 1 },
+          "steps": { "maxItems": 0 }
+        }
+      }
+    },
+    {
+      "description": "A ready plan has no missing facts and at least one step.",
+      "if": { "properties": { "status": { "const": "ready" } }, "required": ["status"] },
+      "then": {
+        "properties": {
+          "missingFacts": { "maxItems": 0 },
+          "steps": { "minItems": 1 }
+        },
+        "required": ["supplied", "decisionSpace"],
+        "$comment": "A ready plan always carries the supplied facts and the decision space they were judged against."
+      }
+    },
+    {
+      "description": "A blocked plan produced no steps and says which capabilities are blocked. An install plan for a surface that answers 404 is not a smaller plan, it is a wrong one.",
+      "if": { "properties": { "status": { "const": "blocked" } }, "required": ["status"] },
+      "then": {
+        "properties": {
+          "missingFacts": { "maxItems": 0 },
+          "steps": { "maxItems": 0 },
+          "blocked": { "minItems": 1 }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "OptionId": {
+      "description": "One option id of one decision-tree question. Kebab-case, published by the contract.",
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "Capability": {
+      "description": "A capability id: one option of the capabilities tree. NOT enumerated here; the set is the platform contract's, and this CLI reads it from the projection.",
+      "$ref": "#/$defs/OptionId"
+    },
+    "IdentityMode": {
+      "description": "An identity mode id: one option of the identity-mode tree.",
+      "$ref": "#/$defs/OptionId"
+    },
+    "ProjectType": {
+      "enum": ["expo-managed", "bare-react-native", "flutter", "web", "unknown"]
+    },
+    "PackageManager": {
+      "enum": ["npm", "pnpm", "yarn", "bun", "not-applicable", "undetermined"]
+    },
+    "Detection": {
+      "type": "object",
+      "required": [
+        "root",
+        "projectType",
+        "projectTypeEvidence",
+        "packageManager",
+        "packageManagerEvidence",
+        "dependencies"
+      ],
+      "properties": {
+        "root": { "type": "string", "minLength": 1 },
+        "projectType": { "$ref": "#/$defs/ProjectType" },
+        "projectTypeEvidence": { "type": "array", "items": { "type": "string" } },
+        "packageManager": { "$ref": "#/$defs/PackageManager" },
+        "packageManagerEvidence": { "type": "array", "items": { "type": "string" } },
+        "dependencies": { "type": "array", "items": { "$ref": "#/$defs/Dependency" } }
+      }
+    },
+    "Dependency": {
+      "type": "object",
+      "required": ["name", "declared", "installed", "source", "scope"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "declared": { "oneOf": [{ "type": "null" }, { "type": "string" }] },
+        "installed": { "oneOf": [{ "type": "null" }, { "type": "string" }] },
+        "source": { "enum": ["package.json", "pubspec.yaml"] },
+        "scope": { "enum": ["dependencies", "devDependencies", "peerDependencies", "sdk"] }
+      }
+    },
+    "BlockedCapability": {
+      "type": "object",
+      "required": ["capability", "reason", "unblockOwner", "requestPath", "capabilityKeys"],
+      "properties": {
+        "capability": { "$ref": "#/$defs/Capability" },
+        "reason": { "type": "string", "minLength": 1 },
+        "unblockOwner": { "type": "string", "minLength": 1 },
+        "requestPath": {
+          "description": "Site-relative path on the partner documentation site. Resolved against the generated site when the contract is compiled, so it cannot point at a page that does not exist.",
+          "type": "string",
+          "pattern": "^/"
+        },
+        "capabilityKeys": {
+          "description": "The capability pack keys this block derives from.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "PlanPrinciple": {
+      "type": "object",
+      "required": ["treeId", "id", "title", "statement", "docPath"],
+      "properties": {
+        "treeId": { "$ref": "#/$defs/OptionId" },
+        "id": { "$ref": "#/$defs/OptionId" },
+        "title": { "type": "string", "minLength": 1 },
+        "statement": { "type": "string", "minLength": 1 },
+        "docPath": { "oneOf": [{ "type": "null" }, { "type": "string", "pattern": "^/" }] }
+      }
+    },
+    "DecisionSpaceProvenance": {
+      "type": "object",
+      "required": ["source", "digest", "trees"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "trees": { "type": "array", "items": { "$ref": "#/$defs/OptionId" } }
+      }
+    },
+    "MissingFact": {
+      "type": "object",
+      "required": ["fact", "reason", "supplyWith"],
+      "properties": {
+        "fact": {
+          "enum": [
+            "decisionTrees",
+            "projectType",
+            "packageManager",
+            "capabilities",
+            "identityMode",
+            "sessionMintLanguage"
+          ]
+        },
+        "reason": { "type": "string", "minLength": 1 },
+        "supplyWith": { "type": "string", "minLength": 1 }
+      }
+    },
+    "PlanStep": {
+      "type": "object",
+      "required": ["id", "phase", "title", "detail", "commands", "files"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+        "phase": { "enum": ["install", "native", "configure", "code", "verify"] },
+        "title": { "type": "string", "minLength": 1 },
+        "detail": { "type": "string", "minLength": 1 },
+        "commands": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "files": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "PlanWarning": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "string", "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$" },
+        "message": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}