@pikku/cli 0.12.82 → 0.12.85

package/skills/pikku-software-archaeology/references/blueprint.schema.json

@@ -0,0 +1,625 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Product Blueprint (.knowledge/) contract",
+  "description": "One schema per output file, keyed by filename under the `files` map. Every extracted concept carries evidence[] and confidence. Facts (observed in code) and inferences (reconstructed intent) must never be merged silently: confidence expresses how directly the evidence supports the claim.",
+  "$defs": {
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["file", "lines"],
+        "properties": {
+          "file": { "type": "string", "description": "repo-relative path" },
+          "lines": { "type": "string", "description": "e.g. '42' or '42-58'" },
+          "note": { "type": "string", "description": "what this location shows" }
+        }
+      }
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "high = behavior directly observed in code/schema; medium = strong inference from multiple signals; low = plausible guess, needs human confirmation"
+    },
+    "conceptName": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Za-z0-9]*$",
+      "description": "PascalCase domain-language name (SendInvoice, InvoicePaid), never a route or filename"
+    }
+  },
+  "files": {
+    "product.json": {
+      "type": "object",
+      "required": ["name", "purpose", "actors", "capabilities", "terminology", "evidence", "confidence"],
+      "properties": {
+        "name": { "type": "string" },
+        "purpose": { "type": "string", "description": "1-3 sentences: what problem, for whom" },
+        "targetUsers": { "type": "array", "items": { "type": "string" } },
+        "actors": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["name", "kind", "description"],
+            "properties": {
+              "name": { "type": "string" },
+              "kind": { "type": "string", "enum": ["human", "system", "external"] },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "capabilities": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "terminology": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["term", "meaning"],
+            "properties": { "term": { "type": "string" }, "meaning": { "type": "string" } }
+          }
+        },
+        "evidence": { "$ref": "#/$defs/evidence" },
+        "confidence": { "$ref": "#/$defs/confidence" }
+      }
+    },
+    "domains.json": {
+      "type": "object",
+      "required": ["domains"],
+      "properties": {
+        "domains": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["name", "description", "entities", "commands", "queries", "events", "evidence", "confidence"],
+            "properties": {
+              "name": { "$ref": "#/$defs/conceptName" },
+              "description": { "type": "string" },
+              "entities": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "commands": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "queries": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "events": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "policies": { "type": "array", "items": { "$ref": "#/$defs/conceptName" }, "description": "policy names from policies.json owned by this domain" },
+              "sourcePaths": { "type": "array", "items": { "type": "string" }, "description": "where this domain currently lives (usually scattered)" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "entities.json": {
+      "type": "object",
+      "required": ["entities"],
+      "properties": {
+        "entities": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "domain", "description", "attributes", "evidence", "confidence"],
+            "properties": {
+              "name": { "$ref": "#/$defs/conceptName" },
+              "domain": { "$ref": "#/$defs/conceptName" },
+              "description": { "type": "string" },
+              "attributes": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "type"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "type": { "type": "string" },
+                    "required": { "type": "boolean" },
+                    "notes": { "type": "string" }
+                  }
+                }
+              },
+              "relationships": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["kind", "target"],
+                  "properties": {
+                    "kind": { "type": "string", "enum": ["belongs-to", "has-many", "has-one", "references", "many-to-many"] },
+                    "target": { "$ref": "#/$defs/conceptName" },
+                    "description": { "type": "string" }
+                  }
+                }
+              },
+              "states": { "type": "array", "items": { "type": "string" } },
+              "transitions": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["from", "to", "trigger"],
+                  "properties": {
+                    "from": { "type": "string" },
+                    "to": { "type": "string" },
+                    "trigger": { "type": "string", "description": "command or event name that causes it" }
+                  }
+                }
+              },
+              "ownership": { "type": "string", "description": "which actor/tenant owns rows of this entity" },
+              "constraints": { "type": "array", "items": { "type": "string" } },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "commands.json": {
+      "type": "object",
+      "required": ["commands"],
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "domain", "actor", "input", "preconditions", "effects", "eventsProduced", "evidence", "confidence"],
+            "properties": {
+              "name": { "$ref": "#/$defs/conceptName", "description": "imperative VerbNoun: ApproveInvoice" },
+              "domain": { "$ref": "#/$defs/conceptName" },
+              "actor": { "type": "string" },
+              "trigger": { "type": "string", "description": "how it is invoked today (route, job, webhook, cron)" },
+              "input": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "type"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "type": { "type": "string" },
+                    "required": { "type": "boolean" }
+                  }
+                }
+              },
+              "preconditions": { "type": "array", "items": { "type": "string" } },
+              "effects": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+              "eventsProduced": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "policies": { "type": "array", "items": { "type": "string" }, "description": "policy names from policies.json enforced here" },
+              "currentImplementation": { "type": "array", "items": { "type": "string" }, "description": "file paths implementing it today" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "queries.json": {
+      "type": "object",
+      "required": ["queries"],
+      "properties": {
+        "queries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "domain", "actor", "description", "returns", "evidence", "confidence"],
+            "properties": {
+              "name": { "$ref": "#/$defs/conceptName", "description": "GetX / ListX / SearchX" },
+              "domain": { "$ref": "#/$defs/conceptName" },
+              "actor": { "type": "string" },
+              "description": { "type": "string" },
+              "input": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "type"],
+                  "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" } }
+                }
+              },
+              "returns": { "type": "string" },
+              "scoping": { "type": "string", "description": "tenancy/visibility rule applied (e.g. 'rows owned by caller only')" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "events.json": {
+      "type": "object",
+      "required": ["events"],
+      "properties": {
+        "events": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "domain", "description", "producedBy", "evidence", "confidence"],
+            "properties": {
+              "name": { "$ref": "#/$defs/conceptName", "description": "past-tense business fact: InvoicePaid. No technical events (ButtonClicked)." },
+              "domain": { "$ref": "#/$defs/conceptName" },
+              "description": { "type": "string" },
+              "producedBy": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "command/workflow names" },
+              "consumedBy": { "type": "array", "items": { "type": "string" }, "description": "what reacts today (email send, status flip, webhook out)" },
+              "payloadHints": { "type": "array", "items": { "type": "string" } },
+              "explicit": { "type": "boolean", "description": "true if the code emits a real event; false if reconstructed from inline side-effects" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "policies.json": {
+      "type": "object",
+      "required": ["policies"],
+      "properties": {
+        "policies": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "rule", "type", "domain", "evidence", "confidence"],
+            "properties": {
+              "name": { "$ref": "#/$defs/conceptName" },
+              "rule": { "type": "string", "description": "plain-language statement: 'Only the invoice owner can send it'" },
+              "type": { "type": "string", "enum": ["authorization", "validation", "state", "business-constraint", "rate-limit"] },
+              "domain": { "$ref": "#/$defs/conceptName" },
+              "enforcedAt": { "type": "array", "items": { "type": "string" }, "description": "every code location enforcing it — multiple locations = divergence risk, note in gaps.json" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "workflows.json": {
+      "type": "object",
+      "required": ["workflows"],
+      "properties": {
+        "workflows": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "kind", "actor", "trigger", "steps", "result", "evidence", "confidence"],
+            "properties": {
+              "name": { "type": "string" },
+              "kind": { "type": "string", "enum": ["user", "admin", "system"] },
+              "actor": { "type": "string" },
+              "trigger": { "type": "string" },
+              "steps": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+              "result": { "type": "string" },
+              "commandsInvolved": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "eventsInvolved": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "schedule": { "type": "string", "description": "cron expression for system workflows, if any" },
+              "scenarios": {
+                "type": "array",
+                "description": "concrete use cases, primarily excavated from the test suite (describe/it names, fixtures, assertions). A scenario sourced from a test is high-confidence by definition.",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "outcome"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "given": { "type": "string" },
+                    "when": { "type": "string" },
+                    "outcome": { "type": "string" },
+                    "fromTest": { "type": "string", "description": "test file path + test name, when sourced from a test" }
+                  }
+                }
+              },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "api.json": {
+      "type": "object",
+      "required": ["surfaces"],
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["kind", "path", "auth", "mapsTo", "evidence"],
+            "properties": {
+              "kind": { "type": "string", "enum": ["rest", "graphql", "rpc", "webhook-in", "webhook-out", "page", "cli", "websocket", "sse"] },
+              "method": { "type": "string" },
+              "path": { "type": "string" },
+              "auth": { "type": "string", "description": "none | session | jwt | api-key | signature | capability-url | ..." },
+              "mapsTo": {
+                "type": "object",
+                "required": ["type", "name"],
+                "properties": {
+                  "type": { "type": "string", "enum": ["command", "query", "event-ingress"], "description": "command/query for normal surfaces. event-ingress ONLY for surfaces that relay an external event without a domain command of their own; its name must be an events.json event. A webhook whose handler changes state maps to a command (usual case)." },
+                  "name": { "$ref": "#/$defs/conceptName" }
+                }
+              },
+              "notes": { "type": "string" },
+              "confidence": { "$ref": "#/$defs/confidence" },
+              "evidence": { "$ref": "#/$defs/evidence" }
+            }
+          }
+        }
+      }
+    },
+    "integrations.json": {
+      "type": "object",
+      "required": ["integrations"],
+      "properties": {
+        "integrations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "category", "purpose", "direction", "importance", "replacementDifficulty", "evidence", "confidence"],
+            "properties": {
+              "name": { "type": "string" },
+              "category": { "type": "string", "description": "payments | email | auth | storage | analytics | llm | sms | ..." },
+              "purpose": { "type": "string" },
+              "dataExchanged": { "type": "array", "items": { "type": "string" } },
+              "direction": { "type": "string", "enum": ["outbound", "inbound", "both"] },
+              "importance": { "type": "string", "enum": ["critical", "important", "peripheral"] },
+              "replacementDifficulty": { "type": "string", "enum": ["trivial", "moderate", "hard"] },
+              "configVia": { "type": "array", "items": { "type": "string" }, "description": "env vars / secrets used" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "architecture.json": {
+      "type": "object",
+      "required": ["components", "datastores"],
+      "properties": {
+        "components": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["name", "kind", "responsibility", "evidence"],
+            "properties": {
+              "name": { "type": "string" },
+              "kind": { "type": "string", "enum": ["frontend", "api", "worker", "job", "webhook-handler", "cli", "service", "proxy", "other"] },
+              "responsibility": { "type": "string" },
+              "dependsOn": { "type": "array", "items": { "type": "string" } },
+              "runtime": { "type": "string", "description": "how it runs today (process, cron, lambda, ...)" },
+              "confidence": { "$ref": "#/$defs/confidence" },
+              "evidence": { "$ref": "#/$defs/evidence" }
+            }
+          }
+        },
+        "datastores": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "kind", "evidence"],
+            "properties": {
+              "name": { "type": "string" },
+              "kind": { "type": "string" },
+              "usedBy": { "type": "array", "items": { "type": "string" } },
+              "notes": { "type": "string" },
+              "confidence": { "$ref": "#/$defs/confidence" },
+              "evidence": { "$ref": "#/$defs/evidence" }
+            }
+          }
+        },
+        "notes": { "type": "array", "items": { "type": "string" }, "description": "deployment constraints worth preserving (ports, raw-body routes, ordering)" }
+      }
+    },
+    "invariants.json": {
+      "type": "object",
+      "required": ["invariants"],
+      "properties": {
+        "invariants": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["statement", "domain", "enforcedBy", "evidence", "confidence"],
+            "properties": {
+              "statement": { "type": "string", "description": "must ALWAYS hold: 'Invoice numbers are sequential per user with no gaps'" },
+              "domain": { "$ref": "#/$defs/conceptName" },
+              "enforcedBy": { "type": "string", "description": "db-constraint | code-guard | convention | nothing (!)" },
+              "atRiskBecause": { "type": "string", "description": "why current enforcement is fragile, if it is" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "gaps.json": {
+      "type": "object",
+      "required": ["gaps"],
+      "properties": {
+        "gaps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["problem", "kind", "impact", "recommendation", "evidence"],
+            "properties": {
+              "problem": { "type": "string" },
+              "kind": { "type": "string", "enum": ["incomplete-feature", "todo", "duplication", "bug", "hack", "dead-code", "unclear-ownership", "architecture", "security", "open-product-decision"] },
+              "impact": { "type": "string" },
+              "recommendation": { "type": "string" },
+              "evidence": { "$ref": "#/$defs/evidence" }
+            }
+          }
+        }
+      }
+    },
+    "migration.json": {
+      "type": "object",
+      "required": ["mappings", "decisionsNeeded"],
+      "properties": {
+        "mappings": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["current", "future", "recommendation"],
+            "properties": {
+              "current": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "file paths in the existing repo" },
+              "future": {
+                "type": "object",
+                "required": ["domain"],
+                "properties": {
+                  "domain": { "$ref": "#/$defs/conceptName" },
+                  "concepts": { "type": "array", "items": { "type": "string" }, "description": "commands/queries/events/entities this code becomes" }
+                }
+              },
+              "recommendation": { "type": "string" }
+            }
+          }
+        },
+        "dropped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "reason"],
+            "properties": { "path": { "type": "string", "description": "file path; for sub-file drops use 'path (symbolName)' when part of a file survives" }, "reason": { "type": "string" } }
+          }
+        },
+        "decisionsNeeded": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["question"],
+            "properties": {
+              "question": { "type": "string" },
+              "options": { "type": "array", "items": { "type": "string" } },
+              "blockedConcepts": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "interfaces.json": {
+      "x-optional": true,
+      "type": "object",
+      "description": "Every way the product is CONSUMED, one entry per channel. The web UI is one channel (detailed further in frontend*.json); CLI, MCP server (for AI agents), OpenAPI/REST, generated SDK, realtime, and webhooks are others. Answers 'who can drive this product and how'.",
+      "required": ["interfaces"],
+      "properties": {
+        "interfaces": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "kind", "audience", "purpose", "evidence", "confidence"],
+            "properties": {
+              "name": { "type": "string" },
+              "kind": { "type": "string", "enum": ["web-ui", "cli", "mcp", "openapi-rest", "graphql", "sdk", "websocket-realtime", "webhook-in", "webhook-out", "email", "other"] },
+              "audience": { "type": "string", "enum": ["human", "developer", "ai-agent", "external-system", "internal"] },
+              "purpose": { "type": "string" },
+              "surfaceCount": { "type": "number", "description": "how many ops/tools/commands/routes this channel exposes" },
+              "generated": { "type": "boolean", "description": "true if generated from another source (OpenAPI from routes, typed SDK, MCP tools from funcs) rather than hand-written" },
+              "domainsServed": { "type": "array", "items": { "$ref": "#/$defs/conceptName" } },
+              "status": { "type": "string", "enum": ["complete", "partial", "stub", "deprecated"] },
+              "notes": { "type": "string" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "frontend.json": {
+      "x-optional": true,
+      "type": "object",
+      "description": "Web-UI app-level shape. Names the framework/router/styling/data/auth so the rebuild can weigh their tradeoffs (e.g. TanStack Start + better-auth + Mantine).",
+      "required": ["framework", "styling", "dataLayer", "auth", "evidence", "confidence"],
+      "properties": {
+        "framework": { "type": "string", "description": "e.g. TanStack Start, Next.js, Remix, Vite SPA" },
+        "rendering": { "type": "string", "enum": ["spa", "ssr", "ssg", "streaming-ssr", "mixed"] },
+        "router": { "type": "string", "description": "e.g. TanStack Router (file-based), React Router" },
+        "styling": { "type": "string", "description": "the design system, e.g. Mantine, Tailwind, MUI, CSS modules" },
+        "designSystemConsistency": { "type": "string", "enum": ["single-system", "mostly-consistent", "mixed", "ad-hoc"], "description": "how uniformly ONE component/theme system is used — the rebuild target is 'everything Mantine', so divergence is porting work" },
+        "designFindings": {
+          "type": "array",
+          "description": "Concrete broken/inconsistent design patterns observed across the UI. Each is a specific, cited observation of a consistency defect — not a taste opinion. These become the design recommendations in the second-opinion report.",
+          "items": {
+            "type": "object",
+            "required": ["pattern", "observation", "recommendation", "evidence"],
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "enum": [
+                  "interaction-inconsistency",
+                  "theming-not-tokenized",
+                  "cross-page-inconsistency",
+                  "component-duplication",
+                  "spacing-typography-scale",
+                  "design-system-bypass",
+                  "accessibility",
+                  "responsive",
+                  "other"
+                ],
+                "description": "interaction-inconsistency = same job done different ways (modal here, drawer there; inconsistent confirm dialogs). theming-not-tokenized = hardcoded colors/spacing/fonts instead of theme tokens/variables. cross-page-inconsistency = the same element (button/header/card) styled differently across pages. component-duplication = several near-identical components for one purpose. spacing-typography-scale = ad-hoc magic numbers off any scale. design-system-bypass = raw HTML/CSS where a design-system component exists. accessibility / responsive = a11y or breakpoint defects."
+              },
+              "observation": { "type": "string", "description": "what is inconsistent, with concrete examples (e.g. 'Add-site uses a Drawer, Edit-site uses a Modal for the same task')" },
+              "impact": { "type": "string", "description": "what it does to the user (feels unpolished/confusing) or to maintenance (a color change means hunting every file)" },
+              "recommendation": { "type": "string", "description": "the fix — usually standardize on one pattern, move values to theme tokens, or extract one shared component" },
+              "severity": { "type": "string", "enum": ["minor", "worth-fixing", "serious"] },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        },
+        "stateManagement": { "type": "string" },
+        "dataLayer": { "type": "string", "description": "how the UI talks to the backend: e.g. pikku-react-query, REST fetch helpers, tRPC, GraphQL client" },
+        "auth": { "type": "string", "description": "client auth mechanism: e.g. better-auth, next-auth, custom JWT" },
+        "buildTool": { "type": "string" },
+        "i18n": { "type": "string", "description": "internationalization approach, or 'none'" },
+        "notes": { "type": "array", "items": { "type": "string" } },
+        "evidence": { "$ref": "#/$defs/evidence" },
+        "confidence": { "$ref": "#/$defs/confidence" }
+      }
+    },
+    "frontend-routes.json": {
+      "x-optional": true,
+      "type": "object",
+      "description": "The page/route tree — what a user can navigate to and do, mapped back to the data (queries/commands) each route uses and the components it renders.",
+      "required": ["routes"],
+      "properties": {
+        "routes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "purpose", "evidence"],
+            "properties": {
+              "path": { "type": "string", "description": "URL path, e.g. /app/sites/:id" },
+              "kind": { "type": "string", "enum": ["page", "layout", "index", "modal-or-drawer", "redirect"] },
+              "purpose": { "type": "string", "description": "what the user does/sees here, in product terms" },
+              "auth": { "type": "string", "description": "none | authenticated | admin | role:xyz" },
+              "dataFrom": { "type": "array", "items": { "type": "string" }, "description": "query/command names (from queries.json/commands.json) this route reads/calls" },
+              "usesComponents": { "type": "array", "items": { "type": "string" }, "description": "component names from frontend-components.json" },
+              "userFlows": { "type": "array", "items": { "type": "string" }, "description": "workflows.json (kind=user) names this route participates in" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    },
+    "frontend-components.json": {
+      "x-optional": true,
+      "type": "object",
+      "description": "Component inventory. The load-bearing field is `rebuild`: it separates components that are trivially rebuildable in the target design system (Mantine) from those carrying bespoke logic that must be carefully PORTED (custom charts, complex tables, canvas, drag/drop). That split is the frontend's real migration cost.",
+      "required": ["components"],
+      "properties": {
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "role", "rebuild", "evidence", "confidence"],
+            "properties": {
+              "name": { "type": "string" },
+              "role": { "type": "string", "enum": ["layout", "navigation", "presentational", "feature", "form", "data-display", "chart", "table", "overlay", "provider", "other"] },
+              "purpose": { "type": "string" },
+              "reuse": { "type": "string", "enum": ["shared", "one-off"], "description": "used across features vs single-use" },
+              "rebuild": {
+                "type": "string",
+                "enum": ["mantine-standard", "mantine-composition", "custom-style", "custom-logic"],
+                "description": "mantine-standard = maps 1:1 to a Mantine component (trivial); mantine-composition = built from Mantine primitives (straightforward); custom-style = diverges visually from the design system (normalize to Mantine); custom-logic = bespoke behavior (chart/table/canvas/drag/editor) that must be PORTED, not re-skinned"
+              },
+              "customLogic": { "type": "string", "description": "REQUIRED when rebuild=custom-logic: what the bespoke behavior is and why a stock component can't replace it" },
+              "dependencies": { "type": "array", "items": { "type": "string" }, "description": "notable libs it pulls in (charting/table/editor) — replacement considerations for the port" },
+              "usedBy": { "type": "array", "items": { "type": "string" }, "description": "routes/components that use it" },
+              "evidence": { "$ref": "#/$defs/evidence" },
+              "confidence": { "$ref": "#/$defs/confidence" }
+            }
+          }
+        }
+      }
+    }
+  }
+}