0xray 4.0.23 → 4.0.25

package/dist/memory-routing/plates.d.ts

@@ -0,0 +1,16 @@
+export declare const PLATE_IDS: readonly ["routing", "governance", "boot", "orchestration", "processor", "reporting", "memory-recall"];
+export type PlateId = (typeof PLATE_IDS)[number];
+export interface PlateStamp {
+    id: PlateId;
+    body: string;
+    sourcePath: string;
+}
+export interface PlateStampResult {
+    id: PlateId;
+    path: string;
+    written: boolean;
+}
+export declare function loadPlate(id: PlateId): PlateStamp;
+export declare function recallPlate(intent: string | null | undefined): PlateStamp | null;
+export declare function stampPlateIfMissing(projectRoot: string, id: PlateId): PlateStampResult;
+export declare function plateStockLine(intent: string | null | undefined): string | null;

package/dist/memory-routing/plates.js

@@ -0,0 +1,71 @@
+/**
+ * Typed plate API. The runtime reader is plates.cjs so Station and the
+ * Cursor preCompact hook share one implementation.
+ */
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const PLATE_IDS = [
+    'routing',
+    'governance',
+    'boot',
+    'orchestration',
+    'processor',
+    'reporting',
+    'memory-recall',
+];
+function isPlateId(value) {
+    return PLATE_IDS.includes(value);
+}
+function isRuntime(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    return (typeof row.loadPlate === 'function'
+        && typeof row.recallPlate === 'function'
+        && typeof row.stampPlateIfMissing === 'function'
+        && typeof row.plateStockLine === 'function'
+        && Array.isArray(row.PLATE_IDS));
+}
+function loadRuntime() {
+    const require = createRequire(import.meta.url);
+    const runtimePath = join(dirname(fileURLToPath(import.meta.url)), '../integrations/hooks/plates.cjs');
+    const loaded = require(runtimePath);
+    if (!isRuntime(loaded)) {
+        throw new Error('plate runtime missing');
+    }
+    return loaded;
+}
+const runtime = loadRuntime();
+function asStamp(value) {
+    if (!value)
+        return null;
+    if (!isPlateId(value.id) || typeof value.body !== 'string') {
+        throw new Error('plate runtime returned an unknown stamp');
+    }
+    return value;
+}
+export function loadPlate(id) {
+    const stamp = asStamp(runtime.loadPlate(id));
+    if (!stamp)
+        throw new Error(`plate missing: ${id}`);
+    return stamp;
+}
+export function recallPlate(intent) {
+    return asStamp(runtime.recallPlate(intent));
+}
+export function stampPlateIfMissing(projectRoot, id) {
+    const result = runtime.stampPlateIfMissing(projectRoot, id);
+    if (!isPlateId(result.id) || typeof result.path !== 'string' || typeof result.written !== 'boolean') {
+        throw new Error('plate runtime returned an unknown stamp result');
+    }
+    return result;
+}
+export function plateStockLine(intent) {
+    const line = runtime.plateStockLine(intent);
+    if (line === null || line === undefined)
+        return null;
+    if (typeof line !== 'string')
+        throw new Error('plate stock line was not text');
+    return line;
+}

package/dist/memory-routing/types.d.ts

@@ -33,6 +33,8 @@ export interface MemoryTaskConfidence {
     complexityBoost: number;
     recommendedAgent: string | null;
 }
+/** Characters kept on one graded lesson line. lessonTrace stores with this cap. */
+export declare const LESSON_TEXT_CAP = 400;
 export interface MemoryLessonLine {
     taskId: string;
     decision: 'success' | 'failure';

package/dist/memory-routing/types.js

@@ -4,4 +4,5 @@
  * Repertoire is one implementation. Any provider exposing createMemoryRoutingProvider()
  * can be loaded via features.json memory_routing.module_path.
  */
-export {};
+/** Characters kept on one graded lesson line. lessonTrace stores with this cap. */
+export const LESSON_TEXT_CAP = 400;

package/dist/processors/implementations/inference-improvement-processor.d.ts

@@ -33,4 +33,9 @@ export declare class InferenceImprovementProcessor extends PostProcessor {
     private generateCodeReviewerPrompt;
     private generateEnforcerPrompt;
     private triggerAgentWorkflow;
+    /**
+     * The operation is finished once its prompt result text is on disk.
+     * One session per operation id. Empty speech writes nothing.
+     */
+    private captureFinishedOperationSpeech;
 }

package/dist/processors/implementations/inference-improvement-processor.js

@@ -13,6 +13,9 @@ import { PostProcessor } from "../processor-interfaces.js";
 import { frameworkLogger } from "../../core/framework-logger.js";
 import { getConfigDir } from "../../core/config-paths.js";
 import { featuresConfigLoader } from "../../core/features-config.js";
+import { captureCompletedInferenceOperation, saveReflectionSession } from "../../inference/session-capture.js";
+import { loadReflectionInferences } from "../../inference/inference-accumulator.js";
+import { InferenceCycle } from "../../inference/inference-cycle.js";
 export class InferenceImprovementProcessor extends PostProcessor {
     name = "inferenceImprovement";
     priority = 5;
@@ -55,7 +58,8 @@ export class InferenceImprovementProcessor extends PostProcessor {
         try {
             const workflowContext = await this.prepareWorkflowContext(directory);
             await this.saveWorkflowContext(directory, workflowContext);
-            await this.triggerAgentWorkflow(workflowContext);
+            const workflowId = await this.triggerAgentWorkflow(workflowContext);
+            await this.captureFinishedOperationSpeech(directory, workflowId);
             await frameworkLogger.log("inference-improvement", "workflow_triggered", "info", {
                 dataFiles: workflowContext.dataLocations.reflections.length +
                     workflowContext.dataLocations.logs.length +
@@ -251,12 +255,107 @@ Final validation and application of approved changes:
         });
         const workflowBase = path.isAbsolute(this.workflowDir) ? this.workflowDir : path.join(process.cwd(), this.workflowDir);
         const outputPath = path.join(workflowBase, "workflow-status.json");
+        const workflowId = `inference-${Date.now()}`;
         fs.writeFileSync(outputPath, JSON.stringify({
             status: "in_progress",
             phase: "data_gathering",
             nextAgent: "researcher",
             message: "Invoke @researcher to begin data gathering phase",
-            workflowId: `inference-${Date.now()}`
+            workflowId
         }, null, 2));
+        return workflowId;
+    }
+    /**
+     * The operation is finished once its prompt result text is on disk.
+     * One session per operation id. Empty speech writes nothing.
+     */
+    async captureFinishedOperationSpeech(directory, currentOperationId) {
+        const workflowBase = path.isAbsolute(this.workflowDir)
+            ? this.workflowDir
+            : path.join(directory, this.workflowDir);
+        const promptsDir = path.join(workflowBase, "prompts");
+        const inferenceDir = path.join(directory, "docs", "inference");
+        const signalNames = readStoredSignalNames(directory);
+        const ids = operationIdsToCapture(promptsDir, currentOperationId);
+        let captured = 0;
+        for (const operationId of ids) {
+            const saved = captureCompletedInferenceOperation({
+                operationId,
+                promptsDir,
+                inferenceDir,
+                signalNames,
+            });
+            if (!saved)
+                continue;
+            captured += 1;
+            await frameworkLogger.log("inference-improvement", "operation_session_captured", "info", { operationId, saved });
+        }
+        let reflectionSaved = 0;
+        for (const session of loadReflectionInferences(inferenceDir)) {
+            const saved = saveReflectionSession(session, inferenceDir);
+            if (!saved)
+                continue;
+            reflectionSaved += 1;
+            await frameworkLogger.log("inference-improvement", "reflection_session_written", "info", {
+                sessionId: session.sessionId,
+                saved,
+            });
+        }
+        if (captured === 0 && reflectionSaved === 0)
+            return;
+        const cycle = new InferenceCycle(directory, undefined, {
+            force: true,
+            skipApply: true,
+            skipDeployVerify: true,
+        });
+        await cycle.maybeRunCycle();
+    }
+}
+function operationIdsToCapture(promptsDir, currentOperationId) {
+    const ids = new Set();
+    if (currentOperationId.trim().length > 0)
+        ids.add(currentOperationId);
+    if (!fs.existsSync(promptsDir))
+        return [...ids];
+    for (const name of fs.readdirSync(promptsDir)) {
+        const stem = /^(inference-\d+)\.result\.(md|txt)$/i.exec(name);
+        if (stem?.[1])
+            ids.add(stem[1]);
+        const full = path.join(promptsDir, name);
+        if (!name.endsWith(".md") && !name.endsWith(".txt"))
+            continue;
+        let text = "";
+        try {
+            text = fs.readFileSync(full, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const declared = /^operation:\s*(\S+)\s*$/im.exec(text);
+        if (declared?.[1])
+            ids.add(declared[1]);
+    }
+    return [...ids];
+}
+function readStoredSignalNames(directory) {
+    const dest = path.join(directory, ".xray", "state", "repertoire", "curated_signals.json");
+    if (!fs.existsSync(dest))
+        return [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(dest, "utf8"));
+        if (!Array.isArray(parsed.signals))
+            return [];
+        const names = [];
+        for (const signal of parsed.signals) {
+            if (!signal || typeof signal !== "object")
+                continue;
+            const name = signal.name;
+            if (typeof name === "string" && name.trim().length > 0)
+                names.push(name.trim());
+        }
+        return names;
+    }
+    catch {
+        return [];
     }
 }

package/dist/processors/implementations/storytelling-trigger-processor.js

@@ -5,7 +5,6 @@ import { PostProcessor } from "../processor-interfaces.js";
 import { frameworkLogger } from "../../core/framework-logger.js";
 import { featuresConfigLoader } from "../../core/features-config.js";
 import { analyzeStructuralPatterns, } from "../../inference/semantic-patterns.js";
-import { captureSessionInference, saveSessionInference, } from "../../inference/session-capture.js";
 export class StorytellingTriggerProcessor extends PostProcessor {
     name = "storytelling-trigger";
     priority = 5;
@@ -327,16 +326,7 @@ export class StorytellingTriggerProcessor extends PostProcessor {
                 inferences.push(`${p.name} pattern detected [${Math.round(p.confidence * 100)}%]: ${p.description}${evidence}`);
             }
             if (semanticPatterns.length > 0) {
-                try {
-                    const session = captureSessionInference(sinceRef, untilRef);
-                    if (session) {
-                        const savedPath = saveSessionInference(session);
-                        inferences.push(`Structured inference captured → ${path.basename(savedPath)}`);
-                    }
-                }
-                catch {
-                    // session capture is best-effort
-                }
+                inferences.push("Semantic patterns stay on the reflection. A graded session comes from finished operation speech, not from commit subjects.");
             }
         }
         if (diff.filesAdded.some(f => f.includes("implementations/") && f.endsWith(".ts"))) {

package/dist/processors/processor-manager.d.ts

@@ -68,7 +68,7 @@ export declare class ProcessorManager {
         success: boolean;
         results: ProcessorResult[];
     }>;
-    executePostProcessors(operation: string, data: any, preResults: ProcessorResult[]): Promise<ProcessorResult[]>;
+    executePostProcessors(operation: string, data: unknown, preResults: ProcessorResult[]): Promise<ProcessorResult[]>;
     private executeProcessor;
     private updateMetrics;
     getProcessorHealth(): ProcessorHealth[];

package/dist/processors/processor-manager.js

@@ -1,6 +1,24 @@
 import { frameworkLogger } from "../core/framework-logger.js";
 import { readdir } from "fs/promises";
-import { join, basename } from "path";
+import { join, basename, dirname } from "path";
+import { fileURLToPath } from "url";
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+function asProcessorContext(ctx) {
+    return ctx;
+}
+function readContextString(ctx, key) {
+    const direct = ctx[key];
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    const toolInput = ctx.toolInput;
+    if (!toolInput || typeof toolInput !== "object")
+        return undefined;
+    const args = toolInput.args;
+    if (!args || typeof args !== "object")
+        return undefined;
+    const value = args[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 export class ProcessorManager {
     processors = new Map();
     metrics = new Map();
@@ -13,24 +31,34 @@ export class ProcessorManager {
         this.registerBuiltInFactories();
     }
     registerProcessorInstance(processor) {
-        if (this.factories.has(processor.name)) {
-            return false;
+        const factoryExisted = this.factories.has(processor.name);
+        if (!factoryExisted) {
+            this.factories.set(processor.name, {
+                execute: async (ctx) => {
+                    const result = await processor.execute(asProcessorContext(ctx));
+                    return result.data;
+                },
+            });
+        }
+        const processorExisted = this.processors.has(processor.name);
+        if (!processorExisted) {
+            this.registerProcessor({
+                name: processor.name,
+                type: processor.type,
+                priority: processor.priority,
+                enabled: processor.enabled,
+            });
         }
-        this.factories.set(processor.name, {
-            execute: async (ctx) => {
-                const result = await processor.execute(ctx);
-                return result.data;
-            },
-        });
         frameworkLogger.log("processor-manager", "auto-discovered-processor", "info", {
             name: processor.name,
             type: processor.type,
             priority: processor.priority,
+            registered: !processorExisted,
         });
-        return true;
+        return !factoryExisted || !processorExisted;
     }
     async discoverProcessors(directory) {
-        const dir = directory || join(__dirname, "implementations");
+        const dir = directory || join(moduleDir, "implementations");
         const discovered = [];
         let files;
         try {
@@ -130,8 +158,8 @@ export class ProcessorManager {
             execute: async (ctx) => {
                 const { LogProtectionProcessor } = await import("./implementations/log-protection-processor.js");
                 const p = new LogProtectionProcessor();
-                const filePath = ctx.filePath || ctx.toolInput?.args?.filePath;
-                const operation = ctx.operation || ctx.toolInput?.args?.operation;
+                const filePath = readContextString(ctx, "filePath");
+                const operation = readContextString(ctx, "operation");
                 const result = await p.execute({ filePath, operation });
                 return result.data;
             },
@@ -229,7 +257,7 @@ export class ProcessorManager {
         f.set("testAutoCreation", {
             execute: async (ctx) => {
                 const { testAutoCreationProcessor } = await import("./implementations/test-auto-creation-processor.js");
-                const result = await testAutoCreationProcessor.execute(ctx);
+                const result = await testAutoCreationProcessor.execute(asProcessorContext(ctx));
                 return { success: result.success, message: result.message, data: result.data };
             },
             init: async () => {
@@ -249,8 +277,8 @@ export class ProcessorManager {
                 const { AgentsMdValidationProcessor } = await import("./implementations/agents-md-validation-processor.js");
                 const p = new AgentsMdValidationProcessor(process.cwd());
                 const result = await p.execute({
-                    tool: ctx.tool || "validate",
-                    operation: ctx.operation || "pre-commit",
+                    tool: readContextString(ctx, "tool") ?? "validate",
+                    operation: readContextString(ctx, "operation") ?? "pre-commit",
                 });
                 return {
                     success: result.success,
@@ -283,7 +311,7 @@ export class ProcessorManager {
         f.set("typescriptCompilation", {
             execute: async (ctx) => {
                 const { runTypeScriptCompilation } = await import("./implementations/typescript-compilation-processor.js");
-                const cwd = ctx.directory || process.cwd();
+                const cwd = readContextString(ctx, "directory") ?? process.cwd();
                 return runTypeScriptCompilation(cwd);
             },
             init: async () => {
@@ -762,10 +790,14 @@ export class ProcessorManager {
         if (Array.isArray(context)) {
             return { valid: true, errors: [] };
         }
-        const contextData = context.data;
+        const record = context;
+        const contextData = record.data;
         if (contextData && typeof contextData !== "object") {
             return { valid: true, errors: [] };
         }
+        const dataRecord = contextData && typeof contextData === "object"
+            ? contextData
+            : {};
         const requiredFields = {
             preValidate: ["operation"],
             codexCompliance: ["operation"],
@@ -779,7 +811,7 @@ export class ProcessorManager {
         };
         const required = requiredFields[processorName] || [];
         for (const field of required) {
-            if (!(field in context) && !(field in (context.data || {}))) {
+            if (!(field in record) && !(field in dataRecord)) {
                 errors.push(`Missing required field: ${field}`);
             }
         }
@@ -787,7 +819,7 @@ export class ProcessorManager {
             frameworkLogger.log("processor-manager", "context-validation-warnings", "info", {
                 processor: processorName,
                 errors,
-                contextKeys: Object.keys(context),
+                contextKeys: Object.keys(record),
             });
         }
         return { valid: errors.length === 0, errors };

package/docs-site/docs/plates/boot.md

@@ -0,0 +1,52 @@
+---
+title: Boot
+sidebar_label: Boot
+---
+
+# Boot
+
+`BootOrchestrator.executeBootSequence` brings the framework up. Processor registration here is the legacy boot list. The live tool gate is the suit pipeline, drawn on the processor plate.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                │
+│                                                            │
+│   ┌─────────────────────┐      ┌────────────────────────┐ │
+│   │ process start       │      │ SIGINT / SIGTERM       │ │
+│   └──────────┬──────────┘      └───────────┬────────────┘ │
+│              └──────────────┬──────────────┘              │
+└─────────────────────────────┼──────────────────────────────┘
+                              v
+┌─────────────────────────────┼──────────────────────────────┐
+│ PROCESSING LAYER            v                              │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ load .xray config                                  │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ orchestrator + delegation session                  │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ session management · activity log                  │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ activateProcessors (PROCESSOR_DEFS)                │  │
+│   │ legacy boot list, then agents and plugins          │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ enforcement · codex compliance                     │  │
+│   │ Dynamo governance integration                      │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+└──────────────────────────────┼────────────────────────────┘
+                               v
+┌──────────────────────────────┼────────────────────────────┐
+│ OUTPUT LAYER                 v                            │
+│   ┌────────────────────────────────────────────────────┐ │
+│   │ BootResult                                         │ │
+│   │ success · agents loaded · errors                   │ │
+│   └────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────┘
+```

package/docs-site/docs/plates/governance.md

@@ -0,0 +1,50 @@
+---
+title: Governance
+sidebar_label: Governance
+---
+
+# Governance
+
+A proposal is deliberated inside the suit, filtered by Dynamo Solar, then merged. The PreToolUse codex gate stands beside the vote.
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                │
+│                                                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ proposal                                           │  │
+│   │ title · description · type                         │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+└──────────────────────────────┼────────────────────────────┘
+                               v
+┌──────────────────────────────┼────────────────────────────┐
+│ PROCESSING LAYER             v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ internal deliberation                              │  │
+│   │ code-review · security-audit · researcher          │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ external filter                                    │  │
+│   │ Dynamo Solar SSOT                                  │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              v                            │
+│   ┌────────────────────────────────────────────────────┐  │
+│   │ merge                                              │  │
+│   │ governance-core weighted vote · decision matrix    │  │
+│   └──────────────────────────┬─────────────────────────┘  │
+│                              │                            │
+│   ┌──────────────────────────┼─────────────────────────┐  │
+│   │ PreToolUse gate          │                         │  │
+│   │ Codex 11 · 29 · 69       │  beside the vote        │  │
+│   └──────────────────────────┼─────────────────────────┘  │
+└──────────────────────────────┼────────────────────────────┘
+                               v
+┌──────────────────────────────┼────────────────────────────┐
+│ OUTPUT LAYER                 v                            │
+│   ┌──────────────────────┐      ┌──────────────────────┐ │
+│   │ vote                 │      │ codex decision       │ │
+│   │ approve / reject     │      │ allow / deny         │ │
+│   └──────────────────────┘      └──────────────────────┘ │
+└────────────────────────────────────────────────────────────┘
+```

package/docs-site/docs/plates/index.md

@@ -0,0 +1,16 @@
+---
+title: Plates
+sidebar_label: Overview
+---
+
+# Plates
+
+A plate is one pipeline, drawn as a stamp. The drawing is the thing a person reads: an input layer, a processing layer, an output layer, and the arrows between them.
+
+These files are the canonical stamps. The Docusaurus sidebar publishes them, and the npm package ships this directory. The worn reader walks up from `dist/integrations/hooks/plates.cjs` to `docs-site/docs/plates/`. One plate, one file.
+
+The station card stays the short subsystem table. That table is the index still on disk after compaction. When the current intent names one pipeline, the card adds a single stock line, `Plate: <id> — .xray/state/plates/<id>.md`. Recall returns that one plate, and a compact can carry its schematic. Lessons stay episodes on signals. A plate is the machine. A lesson is what happened.
+
+The markdown file is the source of truth for that stamp. When the pipeline changes, edit the plate. A worn project may hold a copy at `.xray/state/plates/<id>.md`. The copy is written only when that file is missing, so a local edit stays.
+
+[Routing](./routing.md) · [Governance](./governance.md) · [Boot](./boot.md) · [Orchestration](./orchestration.md) · [Processor](./processor.md) · [Reporting](./reporting.md) · [Memory recall](./memory-recall.md)

package/docs-site/docs/plates/memory-recall.md

@@ -0,0 +1,49 @@
+---
+title: Memory recall
+sidebar_label: Memory recall
+---
+
+# Memory recall
+
+Speech becomes a lesson. Intent names one plate. Compact points at the station card. The card names the stamp. The stamp file is the schematic.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ INPUT LAYER                                                  │
+│                                                              │
+│   ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  │
+│   │ speech       │   │ intent       │   │ compact cut    │  │
+│   └──────┬───────┘   └──────┬───────┘   └───────┬────────┘  │
+└──────────┼──────────────────┼───────────────────┼───────────┘
+           v                  v                   v
+┌──────────┼──────────────────┼───────────────────┼───────────┐
+│ PROCESSING LAYER             │                   │           │
+│          v                  v                   v           │
+│   ┌──────────────┐   ┌──────────────┐   ┌────────────────┐ │
+│   │ speech grades│   │ intent       │   │ compact says   │ │
+│   │ to a lesson  │   │ recalls one  │   │ Read STATION.md│ │
+│   │ on a signal  │   │ plate        │   │                │ │
+│   └──────┬───────┘   └──────┬───────┘   └───────┬────────┘ │
+│          │                  │                   │          │
+│          │                  v                   │          │
+│          │     ┌────────────────────────────┐   │          │
+│          │     │ card keeps the short       │   │          │
+│          │     │ subsystem table            │   │          │
+│          │     │ card names Plate: <id>     │   │          │
+│          │     └─────────────┬──────────────┘   │          │
+└──────────┼───────────────────┼──────────────────┼──────────┘
+           v                   v                  v
+┌──────────┴───────────────────┴──────────────────┴──────────┐
+│ OUTPUT LAYER                                               │
+│                                                            │
+│   ┌────────────────────────────┐  ┌─────────────────────┐ │
+│   │ lesson on the signal       │  │ stamp file          │ │
+│   │ an episode of what happened│  │ the schematic       │ │
+│   └────────────────────────────┘  │ docs-site/docs/     │ │
+│                                   │ plates/<id>.md      │ │
+│                                   │ worn copy only when │ │
+│                                   │ .xray/state/plates/ │ │
+│                                   │ <id>.md is missing  │ │
+│                                   └─────────────────────┘ │
+└──────────────────────────────────────────────────────────────┘
+```