peaks-cli 1.0.12 → 1.0.13

package/dist/src/services/skills/skill-runbook-service.js

@@ -0,0 +1,60 @@
+import { readText } from '../../shared/fs.js';
+import { loadSkillRegistry } from './skill-registry.js';
+const DESTRUCTIVE_APPLY_PATTERNS = [
+    /peaks\s+memory\s+sync[^\n]*--apply/,
+    /peaks\s+memory\s+extract[^\n]*--apply/,
+    /peaks\s+artifacts\s+sync[^\n]*--apply/,
+    /peaks\s+openspec\s+archive[^\n]*--apply/,
+    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/
+];
+const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
+const PEAKS_COMMAND_LINE_PATTERN = /^\s*peaks\s+\w/;
+function extractRunbookSection(body) {
+    const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
+    return match === null ? null : (match[1] ?? null);
+}
+function findDestructiveApplyLines(section) {
+    const lines = section.split(/\r?\n/);
+    return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
+}
+function findPeaksCommandLines(section) {
+    return section
+        .split(/\r?\n/)
+        .filter((line) => PEAKS_COMMAND_LINE_PATTERN.test(line))
+        .map((line) => line.trim());
+}
+export async function inspectSkillRunbook(name, baseDir) {
+    const registry = await loadSkillRegistry(baseDir);
+    const skill = registry.skills.find((entry) => entry.name === name);
+    if (skill === undefined) {
+        throw new Error(`Skill "${name}" not found under skills directory`);
+    }
+    const body = await readText(skill.skillPath);
+    const section = extractRunbookSection(body);
+    if (section === null) {
+        return {
+            name: skill.name,
+            directory: skill.directory,
+            hasRunbook: false,
+            peaksCommandCount: 0,
+            peaksCommandLines: [],
+            destructiveApplyLines: [],
+            hasAuthorizationNote: false,
+            ok: false
+        };
+    }
+    const peaksCommandLines = findPeaksCommandLines(section);
+    const destructiveApplyLines = findDestructiveApplyLines(section);
+    const hasAuthorizationNote = AUTHORIZATION_KEYWORDS_PATTERN.test(section);
+    const ok = destructiveApplyLines.length === 0 || hasAuthorizationNote;
+    return {
+        name: skill.name,
+        directory: skill.directory,
+        hasRunbook: true,
+        peaksCommandCount: peaksCommandLines.length,
+        peaksCommandLines,
+        destructiveApplyLines,
+        hasAuthorizationNote,
+        ok
+    };
+}

package/dist/src/services/standards/project-standards-service.js

@@ -96,20 +96,17 @@ function renderClaudeMd(language) {
         '- peaks-solo summarizes RD and QA standards preflight before end-to-end code workflows.',
         '',
         'Rules:',
-        '- RED LINE: Read `.claude/rules/common/coding-style.md` before editing code, and treat its file-size limits as blockers.',
-        '- RED LINE: Strictly prohibit oversized single files; split large files into cohesive modules before handoff.',
+        '- Read `.claude/rules/common/coding-style.md` before editing code.',
         '- Read `.claude/rules/common/code-review.md` before reviewing changes.',
         '- Read `.claude/rules/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
         `- Read .claude/rules/${language}/coding-style.md for language-specific standards when applicable.`,
         '',
-        'External references: https://github.com/affaan-m/everything-claude-code and https://github.com/SquabbyZ/andrej-karpathy-skills are used as curated references only. Treat andrej-karpathy-skills code quality guidance as a red line during peaks-rd implementation. Do not execute or install external content without explicit approval.',
+        'External reference: https://github.com/affaan-m/everything-claude-code is used as a curated reference only. Do not execute or install external content without explicit approval.',
         ''
     ].join('\n');
 }
 function renderCommonCodingStyle() {
-    return `${renderHeader('Common Coding Standards')}- RED LINE: Strictly prohibit oversized single files; split large files into cohesive modules before handoff.
-- RED LINE: Treat https://github.com/SquabbyZ/andrej-karpathy-skills code quality guidance as a blocker for peaks-rd implementation.
-- Prefer simple, readable code over clever abstractions.
+    return `${renderHeader('Common Coding Standards')}- Prefer simple, readable code over clever abstractions.
 - Keep functions focused and files cohesive.
 - Use immutable updates unless a language-specific convention explicitly favors mutation.
 - Validate user input, external data, file paths, and configuration at system boundaries.
@@ -117,9 +114,7 @@ function renderCommonCodingStyle() {
 `;
 }
 function renderCodeReview() {
-    return `${renderHeader('Code Review Standards')}- RED LINE: Block oversized single-file changes and require cohesive module splits before approval.
-- RED LINE: Treat https://github.com/SquabbyZ/andrej-karpathy-skills code quality guidance as a blocker during review.
-- Review diffs for correctness, maintainability, test coverage, and regression risk.
+    return `${renderHeader('Code Review Standards')}- Review diffs for correctness, maintainability, test coverage, and regression risk.
 - Treat missing tests for changed behavior as a blocker unless the change is documentation-only.
 - Verify code paths that handle filesystem, external APIs, credentials, user input, or generated artifacts.
 - peaks-qa must use this guidance as part of code workflow preflight and final verification.

package/dist/src/services/understand/understand-scan-service.d.ts

@@ -0,0 +1,28 @@
+import type { UnderstandScanReport } from './understand-types.js';
+export type UnderstandScanOptions = {
+    projectRoot: string;
+    artifactDir?: string;
+};
+export declare function scanUnderstandAnything(options: UnderstandScanOptions): Promise<UnderstandScanReport>;
+export type UnderstandGraphSummary = {
+    exists: boolean;
+    path: string;
+    generatedAt: string | null;
+    topLevelFields: string[];
+    counts: {
+        nodes: number;
+        edges: number;
+        layers: number;
+        tours: number;
+    };
+    layerNames: string[];
+    tourNames: string[];
+    sampleNodes: string[];
+    parseError?: string;
+};
+export type SummarizeKnowledgeGraphOptions = {
+    projectRoot: string;
+    artifactDir?: string;
+    sampleSize?: number;
+};
+export declare function summarizeKnowledgeGraph(options: SummarizeKnowledgeGraphOptions): Promise<UnderstandGraphSummary>;

package/dist/src/services/understand/understand-scan-service.js

@@ -0,0 +1,157 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+import { getErrorMessage } from '../../shared/result.js';
+function defaultArtifactDir(projectRoot) {
+    return join(projectRoot, '.understand-anything');
+}
+function countArrayField(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value.length : 0;
+}
+async function readFlag(path) {
+    return { exists: await pathExists(path), path };
+}
+async function readGraph(graphPath) {
+    if (!(await pathExists(graphPath))) {
+        return { exists: false, path: graphPath };
+    }
+    const stats = await stat(graphPath);
+    const raw = await readText(graphPath);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                exists: true,
+                path: graphPath,
+                sizeBytes: stats.size,
+                parseError: 'knowledge-graph.json must be a JSON object'
+            };
+        }
+        const record = parsed;
+        return {
+            exists: true,
+            path: graphPath,
+            sizeBytes: stats.size,
+            topLevelFields: Object.keys(record).sort(),
+            counts: {
+                nodes: countArrayField(record, 'nodes'),
+                edges: countArrayField(record, 'edges'),
+                layers: countArrayField(record, 'layers'),
+                tours: countArrayField(record, 'tours')
+            }
+        };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            path: graphPath,
+            sizeBytes: stats.size,
+            parseError: getErrorMessage(error)
+        };
+    }
+}
+export async function scanUnderstandAnything(options) {
+    const artifactDir = options.artifactDir ?? defaultArtifactDir(options.projectRoot);
+    const exists = await isDirectory(artifactDir);
+    if (!exists) {
+        return {
+            exists: false,
+            artifactDir,
+            graph: { exists: false, path: join(artifactDir, 'knowledge-graph.json') },
+            intermediate: { exists: false, path: join(artifactDir, 'intermediate') },
+            diffOverlay: { exists: false, path: join(artifactDir, 'diff-overlay.json') }
+        };
+    }
+    const graph = await readGraph(join(artifactDir, 'knowledge-graph.json'));
+    const intermediate = await readFlag(join(artifactDir, 'intermediate'));
+    const diffOverlay = await readFlag(join(artifactDir, 'diff-overlay.json'));
+    return { exists: true, artifactDir, graph, intermediate, diffOverlay };
+}
+function pickStringId(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    for (const key of ['id', 'path', 'name', 'label']) {
+        const candidate = record[key];
+        if (typeof candidate === 'string' && candidate.length > 0) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function pickStringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function pickNameArray(record, key) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => {
+        if (typeof entry === 'string') {
+            return entry;
+        }
+        return pickStringId(entry);
+    })
+        .filter((entry) => entry !== null);
+}
+export async function summarizeKnowledgeGraph(options) {
+    const scanOptions = { projectRoot: options.projectRoot };
+    if (options.artifactDir !== undefined) {
+        scanOptions.artifactDir = options.artifactDir;
+    }
+    const scan = await scanUnderstandAnything(scanOptions);
+    const sampleSize = options.sampleSize ?? 5;
+    if (!scan.graph.exists) {
+        return {
+            exists: false,
+            path: scan.graph.path,
+            generatedAt: null,
+            topLevelFields: [],
+            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
+            layerNames: [],
+            tourNames: [],
+            sampleNodes: []
+        };
+    }
+    if (scan.graph.parseError !== undefined) {
+        return {
+            exists: true,
+            path: scan.graph.path,
+            generatedAt: null,
+            topLevelFields: [],
+            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
+            layerNames: [],
+            tourNames: [],
+            sampleNodes: [],
+            parseError: scan.graph.parseError
+        };
+    }
+    const raw = await readText(scan.graph.path);
+    const parsed = JSON.parse(raw);
+    const record = parsed;
+    const generatedAt = pickStringField(record, 'generatedAt');
+    const nodes = Array.isArray(record.nodes) ? record.nodes : [];
+    const sampleNodes = nodes.slice(0, sampleSize)
+        .map((entry) => pickStringId(entry))
+        .filter((entry) => entry !== null);
+    return {
+        exists: true,
+        path: scan.graph.path,
+        generatedAt,
+        topLevelFields: Object.keys(record).sort(),
+        counts: {
+            nodes: countArrayField(record, 'nodes'),
+            edges: countArrayField(record, 'edges'),
+            layers: countArrayField(record, 'layers'),
+            tours: countArrayField(record, 'tours')
+        },
+        layerNames: pickNameArray(record, 'layers'),
+        tourNames: pickNameArray(record, 'tours'),
+        sampleNodes
+    };
+}

package/dist/src/services/understand/understand-types.d.ts

@@ -0,0 +1,24 @@
+export type UnderstandGraphReport = {
+    exists: boolean;
+    path: string;
+    sizeBytes?: number;
+    topLevelFields?: string[];
+    counts?: {
+        nodes: number;
+        edges: number;
+        layers: number;
+        tours: number;
+    };
+    parseError?: string;
+};
+export type UnderstandFlagReport = {
+    exists: boolean;
+    path: string;
+};
+export type UnderstandScanReport = {
+    exists: boolean;
+    artifactDir: string;
+    graph: UnderstandGraphReport;
+    intermediate: UnderstandFlagReport;
+    diffOverlay: UnderstandFlagReport;
+};

package/dist/src/services/understand/understand-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/shared/json-schema-mini.d.ts

@@ -0,0 +1,10 @@
+export type JsonSchemaIssue = {
+    path: string;
+    message: string;
+};
+export type JsonSchemaResult = {
+    valid: boolean;
+    errors: JsonSchemaIssue[];
+};
+export type JsonSchemaNode = Record<string, unknown>;
+export declare function validateAgainstSchema(value: unknown, schema: JsonSchemaNode): JsonSchemaResult;

package/dist/src/shared/json-schema-mini.js

@@ -0,0 +1,113 @@
+function joinPath(parent, segment) {
+    if (parent === '/') {
+        return `/${segment}`;
+    }
+    return `${parent}/${segment}`;
+}
+function typeOf(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (Number.isInteger(value)) {
+        return 'integer';
+    }
+    return typeof value;
+}
+function matchesType(value, expected) {
+    if (expected === 'integer') {
+        return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value);
+    }
+    if (expected === 'number') {
+        return typeof value === 'number' && Number.isFinite(value);
+    }
+    if (expected === 'array') {
+        return Array.isArray(value);
+    }
+    if (expected === 'null') {
+        return value === null;
+    }
+    if (expected === 'object') {
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+    return typeof value === expected;
+}
+function validateNode(value, schema, path, errors) {
+    if (Array.isArray(schema.oneOf)) {
+        const branches = schema.oneOf;
+        const branchErrors = [];
+        let matched = false;
+        for (const branch of branches) {
+            const sink = [];
+            validateNode(value, branch, path, sink);
+            if (sink.length === 0) {
+                matched = true;
+                break;
+            }
+            branchErrors.push(sink);
+        }
+        if (!matched) {
+            const detail = branchErrors.map((sink) => sink.map((issue) => issue.message).join(' / ')).join(' | ');
+            errors.push({ path, message: `does not match any oneOf branch (${detail})` });
+        }
+        return;
+    }
+    const expectedType = typeof schema.type === 'string' ? schema.type : null;
+    if (expectedType !== null && !matchesType(value, expectedType)) {
+        errors.push({ path, message: `expected type ${expectedType}, got ${typeOf(value)}` });
+        return;
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+            errors.push({ path, message: `string shorter than minLength ${schema.minLength}` });
+        }
+        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern).test(value)) {
+            errors.push({ path, message: `string does not match pattern ${schema.pattern}` });
+        }
+        if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+            errors.push({ path, message: `value ${JSON.stringify(value)} is not in enum` });
+        }
+        return;
+    }
+    if (typeof value === 'number') {
+        if (typeof schema.minimum === 'number' && value < schema.minimum) {
+            errors.push({ path, message: `number below minimum ${schema.minimum}` });
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (schema.items !== undefined) {
+            const itemSchema = schema.items;
+            value.forEach((entry, index) => {
+                validateNode(entry, itemSchema, joinPath(path, index), errors);
+            });
+        }
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (!Object.prototype.hasOwnProperty.call(record, key)) {
+                    errors.push({ path, message: `missing required property: ${key}` });
+                }
+            }
+        }
+        const properties = schema.properties;
+        if (properties !== null && typeof properties === 'object' && !Array.isArray(properties)) {
+            const propertyMap = properties;
+            for (const [key, child] of Object.entries(propertyMap)) {
+                if (Object.prototype.hasOwnProperty.call(record, key)) {
+                    validateNode(record[key], child, joinPath(path, key), errors);
+                }
+            }
+        }
+    }
+}
+export function validateAgainstSchema(value, schema) {
+    const errors = [];
+    validateNode(value, schema, '/', errors);
+    return { valid: errors.length === 0, errors };
+}

package/dist/src/shared/paths.d.ts

@@ -3,4 +3,4 @@ export declare const skillsDir: string;
 export declare const schemasDir: string;
 export declare const templatesDir: string;
 export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt"];
-export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json"];
+export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json"];

package/dist/src/shared/paths.js

@@ -36,5 +36,13 @@ export const requiredSchemaFiles = [
     'capability-item.schema.json',
     'capability-availability.schema.json',
     'recommendation-plan.schema.json',
-    'artifact-workspace.schema.json'
+    'artifact-workspace.schema.json',
+    'mcp-server.schema.json',
+    'mcp-install-spec.schema.json',
+    'mcp-install-plan.schema.json',
+    'mcp-apply-result.schema.json',
+    'openspec-change-summary.schema.json',
+    'openspec-render-request.schema.json',
+    'openspec-validation-result.schema.json',
+    'doctor-report.schema.json'
 ];

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.12";
+export declare const CLI_VERSION = "1.0.13";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.12";
+export const CLI_VERSION = "1.0.13";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -21,7 +21,6 @@
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
     "scripts/watch.mjs",
-    "scripts/strip-internal-exports.mjs",
     "skills/**",
     "!skills/**/test-prompts.json",
     "!skills/**/.DS_Store",
@@ -29,14 +28,13 @@
     "schemas/*.json"
   ],
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json && node ./scripts/strip-internal-exports.mjs",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "postinstall": "node ./scripts/install-skills.mjs",
     "dev": "tsx src/cli/index.ts",
     "dev:watch": "node ./scripts/watch.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint eslint.config.js \"bin/**/*.js\" \"scripts/**/*.mjs\" \"src/**/*.ts\" \"tests/**/*.ts\" vitest.config.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "engines": {
@@ -48,14 +46,10 @@
     "shadcn": "4.7.0"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^2.1.8",
-    "eslint": "^10.4.0",
-    "globals": "^17.6.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.59.4",
     "vitest": "^2.1.8"
   }
 }

package/schemas/doctor-report.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks Doctor Report",
+  "description": "The envelope emitted by `peaks doctor --json` (data field). Each check.id uses a `<prefix>:<target>` form so callers can route follow-up actions per category.",
+  "type": "object",
+  "required": ["checks", "summary"],
+  "properties": {
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "ok", "message"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|schema|config|doctor-self|capability):[A-Za-z0-9][A-Za-z0-9._-]*$",
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
+          },
+          "ok": { "type": "boolean" },
+          "message": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["ok", "passed", "failed"],
+      "properties": {
+        "ok": { "type": "boolean" },
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/mcp-apply-result.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks MCP Apply Result",
+  "type": "object",
+  "required": ["capabilityId", "action", "backup", "written", "envCheck"],
+  "properties": {
+    "capabilityId": { "type": "string", "minLength": 1 },
+    "action": {
+      "type": "string",
+      "enum": ["add", "update", "claimed", "noop"],
+      "description": "claimed is returned when an existing non-peaks-managed entry was overwritten with --claim."
+    },
+    "backup": {
+      "type": "object",
+      "required": ["path", "skipped"],
+      "properties": {
+        "path": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "minLength": 1 }
+          ],
+          "description": "Absolute path to the backup settings.json copy. Null when no prior settings existed or skipped is true."
+        },
+        "skipped": {
+          "type": "boolean",
+          "description": "True when action was noop and no write occurred."
+        }
+      }
+    },
+    "written": {
+      "type": "object",
+      "required": ["settingsPath", "managedMarkerPath"],
+      "properties": {
+        "settingsPath": { "type": "string", "minLength": 1 },
+        "managedMarkerPath": { "type": "string", "minLength": 1 }
+      }
+    },
+    "envCheck": {
+      "type": "object",
+      "required": ["missing"],
+      "properties": {
+        "missing": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/mcp-install-plan.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks MCP Install Plan",
+  "type": "object",
+  "required": ["capabilityId", "action", "spec", "current", "envCheck", "diff", "nextActions"],
+  "properties": {
+    "capabilityId": { "type": "string", "minLength": 1 },
+    "action": {
+      "type": "string",
+      "enum": ["add", "update", "noop", "conflict", "unknown-capability"]
+    },
+    "spec": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "mcp-install-spec.schema.json" }
+      ]
+    },
+    "current": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "mcp-server.schema.json" }
+      ]
+    },
+    "envCheck": {
+      "type": "object",
+      "required": ["missing"],
+      "properties": {
+        "missing": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Env var keys that are not set or are empty."
+        }
+      }
+    },
+    "diff": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "object",
+              "required": ["before", "after"],
+              "properties": {
+                "before": { "type": "string" },
+                "after": { "type": "string" }
+              }
+            },
+            "args": {
+              "type": "object",
+              "required": ["before", "after"],
+              "properties": {
+                "before": { "type": "array", "items": { "type": "string" } },
+                "after": { "type": "array", "items": { "type": "string" } }
+              }
+            },
+            "envKeys": {
+              "type": "object",
+              "required": ["before", "after"],
+              "properties": {
+                "before": { "type": "array", "items": { "type": "string" } },
+                "after": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "nextActions": { "type": "array", "items": { "type": "string" } }
+  }
+}