@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/knowledge.json

@@ -0,0 +1,2940 @@
+{
+  "concepts": [
+    {
+      "summary": "Scope selects which organization and agent context reads and writes apply to.",
+      "problem": "Acting without explicit scope can touch the wrong workspace.",
+      "why": "Memorix isolates tenants and agent inheritance behind deliberate scope selection.",
+      "mentalModel": "Scope is a workspace lock, not decoration.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "agents-inheritance",
+        "effective-metadata"
+      ],
+      "next": [
+        "agents-inheritance"
+      ],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "scope"
+      ],
+      "id": "org-agent-scope",
+      "type": "concept",
+      "title": "Organization and agent scope",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Child agents inherit definitions; Studio shows the effective result.",
+      "problem": "Reading only local files hides parent contributions and conflicts.",
+      "why": "Inheritance keeps shared definitions DRY while allowing replacement and additive behavior.",
+      "mentalModel": "Oldest-parent-first resolution into an effective model.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "org-agent-scope"
+      ],
+      "related": [
+        "effective-metadata"
+      ],
+      "next": [
+        "effective-metadata"
+      ],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "agents"
+      ],
+      "id": "agents-inheritance",
+      "type": "concept",
+      "title": "Agents and inheritance",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Sources feed Memory; Memory holds durable product records.",
+      "problem": "Without a clear boundary, pipelines and storage blur.",
+      "why": "Separating ingest from durable memory keeps provenance and retries understandable.",
+      "mentalModel": "Source → validated content → Memory record.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "raw-records"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "memory"
+      ],
+      "id": "sources-and-memory",
+      "type": "concept",
+      "title": "Sources and Memory",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Identity, payload shape, and category are separate axes.",
+      "problem": "Collapsing them forces brittle one-size schemas.",
+      "why": "Memorix needs the same subject to carry multiple content shapes over time.",
+      "mentalModel": "Object identity × content type × category.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "raw-records",
+        "composition"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "model"
+      ],
+      "id": "object-content-category",
+      "type": "concept",
+      "title": "Object type, content type, and data category",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Validation does not install; installation requires confirmation.",
+      "problem": "Auto-applying packs or proposals would silently change runtime behavior.",
+      "why": "Reviewable, deterministic, reversible configuration changes.",
+      "mentalModel": "Treat metadata packs like deployments.",
+      "audiences": [
+        "builders",
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "intelligence-proposals",
+        "effective-metadata"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Intelligence proposals never auto-install"
+      ],
+      "alternatives": [],
+      "tags": [
+        "metadata"
+      ],
+      "id": "explicit-metadata-installation",
+      "type": "concept",
+      "title": "Explicit metadata validation and installation",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "The resolved definitions after inheritance and installation.",
+      "problem": "Authors confuse source files with what the runtime actually uses.",
+      "why": "Readers and writers must see the effective model before mutating data.",
+      "mentalModel": "Installed + inherited → effective.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "explicit-metadata-installation",
+        "agents-inheritance"
+      ],
+      "related": [
+        "org-agent-scope"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "metadata"
+      ],
+      "id": "effective-metadata",
+      "type": "concept",
+      "title": "Effective metadata",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "An abstract is a virtual union projected through bindings — not stored rows.",
+      "problem": "Callers otherwise duplicate union queries across concrete types.",
+      "why": "Abstracts give stable read models without denormalizing storage.",
+      "mentalModel": "Bindings map concrete members into an abstract projection.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "people-union"
+      ],
+      "next": [
+        "people-union"
+      ],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "abstracts"
+      ],
+      "id": "abstracts-bindings",
+      "type": "concept",
+      "title": "Abstracts and bindings",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "People combines employees and contractors through explicit bindings.",
+      "problem": "UIs need one people list without merging tables by hand.",
+      "why": "Abstract projection preserves concrete types while enabling combined reads.",
+      "mentalModel": "employees ∪ contractors → People.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "abstracts-bindings"
+      ],
+      "related": [
+        "composition"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "abstracts"
+      ],
+      "id": "people-union",
+      "type": "concept",
+      "title": "People union",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Mappings describe how source shapes become Memory content.",
+      "problem": "Ad-hoc transforms hide field provenance.",
+      "why": "Explicit mappings make validation and recovery possible.",
+      "mentalModel": "Declared mapping, not implicit guesswork.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "raw-records"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "mapping"
+      ],
+      "id": "mappings-transforms",
+      "type": "concept",
+      "title": "Mappings and transforms",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Raw retains the original payload beside envelope metadata.",
+      "problem": "Losing raw makes audits and remapping impossible.",
+      "why": "Memorix keeps evidence of what arrived.",
+      "mentalModel": "Envelope + raw body; choose views deliberately.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "composition",
+        "object-content-category"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "records"
+      ],
+      "id": "raw-records",
+      "type": "concept",
+      "title": "Raw records",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Multiple content instances can belong to one subject when composition is explicit.",
+      "problem": "Callers otherwise assume one row per subject.",
+      "why": "Subjects accumulate history and alternate content types.",
+      "mentalModel": "Subject → composed bag of content instances.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "raw-records"
+      ],
+      "related": [
+        "people-union"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "composition"
+      ],
+      "id": "composition",
+      "type": "concept",
+      "title": "Same-subject composition",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "A relationship definition is metadata describing allowed links — not a stored edge on a record.",
+      "problem": "Confusing definitions with instances breaks traversal expectations.",
+      "why": "Definitions make forward/inverse traversal predictable.",
+      "mentalModel": "Definition first; references second.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "relationship-references",
+        "traversal"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "relationships"
+      ],
+      "id": "relationship-definitions",
+      "type": "concept",
+      "title": "Relationship definitions",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Records store relationship references that point at targets under a definition.",
+      "problem": "Without stored refs, graphs cannot be rebuilt or verified.",
+      "why": "References are the durable facts; definitions are the schema.",
+      "mentalModel": "Record holds refs typed by definition id.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "relationship-definitions"
+      ],
+      "related": [
+        "resolved-unresolved"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "relationships"
+      ],
+      "id": "relationship-references",
+      "type": "concept",
+      "title": "Stored relationship references",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Traversal follows definitions forward or inverse, optionally expanding targets.",
+      "problem": "Callers guess direction and miss inverse edges.",
+      "why": "Explicit direction matches authored relationship semantics.",
+      "mentalModel": "Pick definition → direction → expand or not.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "relationship-references"
+      ],
+      "related": [
+        "resolved-unresolved"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "relationships"
+      ],
+      "id": "traversal",
+      "type": "concept",
+      "title": "Forward and inverse traversal",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Unresolved targets are retained and shown — not silently dropped.",
+      "problem": "Hiding unresolved links loses operational truth.",
+      "why": "Operators need to repair, wait, or escalate deliberately.",
+      "mentalModel": "Absence of a target is a first-class state.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "traversal"
+      ],
+      "related": [
+        "relationship-references"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "relationships"
+      ],
+      "id": "resolved-unresolved",
+      "type": "concept",
+      "title": "Resolved and unresolved relationships",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Writes carry an expected revision; stale writers cannot overwrite newer data.",
+      "problem": "Lost updates when concurrent writers race.",
+      "why": "Revision preconditions preserve newer data and force explicit recovery.",
+      "mentalModel": "Load → mutate → write with expected revision → reload on conflict.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "raw-records"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "concurrency"
+      ],
+      "id": "record-revisions",
+      "type": "concept",
+      "title": "Record revisions and stale-write conflicts",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Analysis captures evaluated evidence distinct from operational decisions.",
+      "problem": "Mixing analysis with decisions hides how conclusions formed.",
+      "why": "Separating analysis keeps auditability and replay.",
+      "mentalModel": "Evidence → analysis → (later) decision.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "decisions-content",
+        "intelligence-proposals"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "analysis"
+      ],
+      "id": "analysis-objects",
+      "type": "concept",
+      "title": "Analysis objects",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Decisions record chosen actions distinct from analysis content.",
+      "problem": "If decisions are only implied in chats, systems cannot act reliably.",
+      "why": "Durable decisions drive workflows and audits.",
+      "mentalModel": "Analysis informs; decision commits.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "analysis-objects"
+      ],
+      "related": [
+        "intelligence-proposals"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "decisions"
+      ],
+      "id": "decisions-content",
+      "type": "concept",
+      "title": "Decisions",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    },
+    {
+      "summary": "Intelligence may propose metadata or actions but never auto-installs them.",
+      "problem": "Silent installation would violate reviewability.",
+      "why": "Humans remain the confirmation boundary for runtime-changing packs.",
+      "mentalModel": "Propose → review → explicit install or reject.",
+      "audiences": [
+        "builders",
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "explicit-metadata-installation"
+      ],
+      "related": [
+        "explicit-metadata-installation"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Proposals never auto-install"
+      ],
+      "alternatives": [],
+      "tags": [
+        "intelligence"
+      ],
+      "id": "intelligence-proposals",
+      "type": "concept",
+      "title": "Intelligence proposals",
+      "visualIds": [],
+      "diagramIds": [],
+      "referenceIds": []
+    }
+  ],
+  "guides": [
+    {
+      "summary": "Set the workspace scope before reading or writing.",
+      "why": "Wrong scope violates isolation.",
+      "audiences": [
+        "builders",
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "org-agent-scope"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Do not mutate another organization's data"
+      ],
+      "alternatives": [],
+      "confirmationRequired": false,
+      "tags": [
+        "scope"
+      ],
+      "id": "apply-scope",
+      "type": "guide",
+      "title": "Select and apply organization/agent scope",
+      "useWhen": [
+        "Entering Studio or an API session"
+      ],
+      "doNotUseWhen": [
+        "You already confirmed the active scope matches the task"
+      ],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "choose-org",
+          "title": "Choose organization",
+          "expectedResult": "Org selected",
+          "optional": false
+        },
+        {
+          "id": "choose-agent",
+          "title": "Choose agent",
+          "expectedResult": "Agent selected",
+          "optional": false
+        },
+        {
+          "id": "apply",
+          "title": "Apply scope",
+          "expectedResult": "UI/API uses that scope",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Subsequent reads show the expected workspace"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Confirm effective definitions before mutating records.",
+      "why": "Source files alone may not match runtime.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "apply-scope"
+      ],
+      "related": [
+        "effective-metadata"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Writes assume the effective model"
+      ],
+      "alternatives": [],
+      "tags": [
+        "metadata"
+      ],
+      "id": "inspect-effective-metadata",
+      "type": "guide",
+      "title": "Inspect effective metadata before read/write",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "open-effective",
+          "title": "Open effective metadata view",
+          "expectedResult": "Resolved definitions visible",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Target object/content types appear as expected"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Pick the fidelity that matches the caller goal.",
+      "why": "Wrong view wastes work or loses detail.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "raw-records",
+        "composition",
+        "people-union"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "access"
+      ],
+      "id": "choose-access-method",
+      "type": "guide",
+      "title": "Choose raw, composed, or abstract access",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "decide",
+          "title": "Match goal to raw vs composition vs abstract",
+          "expectedResult": "Access method chosen",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Response shape matches the chosen view"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Read a record, write with expected revision, verify.",
+      "why": "Revision preconditions prevent lost updates.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "record-revisions"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Never omit expected revision on conditional writes"
+      ],
+      "alternatives": [],
+      "tags": [
+        "concurrency"
+      ],
+      "id": "first-revision-safe-write",
+      "type": "guide",
+      "title": "Perform a first revision-safe read/write",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "read",
+          "title": "Read current record and revision",
+          "expectedResult": "Revision N known",
+          "optional": false
+        },
+        {
+          "id": "write",
+          "title": "Write with expected revision N",
+          "expectedResult": "Success or conflict",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Record shows revision N+1 on success"
+      ],
+      "recovery": [
+        "On conflict, follow reload-and-retry guide"
+      ],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Recover safely when a stale write is rejected.",
+      "why": "The record was not mutated; retry from current state.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "record-revisions"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Do not force overwrite without comparing meaning"
+      ],
+      "alternatives": [],
+      "confirmationRequired": true,
+      "tags": [
+        "concurrency"
+      ],
+      "id": "reload-retry-conflict",
+      "type": "guide",
+      "title": "Reload, compare, and retry after a revision conflict",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "reload",
+          "title": "Reload current revision",
+          "expectedResult": "Fresh envelope",
+          "optional": false
+        },
+        {
+          "id": "compare",
+          "title": "Compare intended change to current meaning",
+          "expectedResult": "Decision to reapply or escalate",
+          "optional": false,
+          "confirmationRequired": true
+        },
+        {
+          "id": "retry",
+          "title": "Retry write with new expected revision",
+          "expectedResult": "Success or escalate",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "No silent overwrite of newer fields"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": [
+        "stale-revision-conflict"
+      ]
+    },
+    {
+      "summary": "Validate first, then confirm installation.",
+      "why": "Validation alone must not change runtime.",
+      "audiences": [
+        "builders",
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "explicit-metadata-installation"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Intelligence proposals never auto-install"
+      ],
+      "alternatives": [],
+      "confirmationRequired": true,
+      "tags": [
+        "metadata"
+      ],
+      "id": "validate-install-pack",
+      "type": "guide",
+      "title": "Validate and explicitly install a metadata pack",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "validate",
+          "title": "Validate pack",
+          "expectedResult": "Validation report",
+          "optional": false
+        },
+        {
+          "id": "confirm",
+          "title": "Confirm install",
+          "expectedResult": "User confirms",
+          "optional": false,
+          "confirmationRequired": true
+        },
+        {
+          "id": "install",
+          "title": "Install pack",
+          "expectedResult": "Effective metadata updates",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Effective metadata reflects the pack"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Author a definition, store a reference, traverse forward/inverse.",
+      "why": "Traversal is only predictable with explicit definitions.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "relationship-definitions",
+        "traversal"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "relationships"
+      ],
+      "id": "define-traverse-relationship",
+      "type": "guide",
+      "title": "Define and traverse a relationship",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "define",
+          "title": "Author relationship definition",
+          "expectedResult": "Definition installed",
+          "optional": false
+        },
+        {
+          "id": "store",
+          "title": "Store relationship reference",
+          "expectedResult": "Ref on record",
+          "optional": false
+        },
+        {
+          "id": "traverse",
+          "title": "Traverse with chosen direction",
+          "expectedResult": "Targets returned",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Forward and inverse match the definition"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Distinguish intentional unresolved from broken targets.",
+      "why": "Unresolved is retained as a first-class state.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "resolved-unresolved"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "relationships"
+      ],
+      "id": "diagnose-unresolved",
+      "type": "guide",
+      "title": "Diagnose an unresolved relationship target",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "inspect",
+          "title": "Inspect unresolved marker and definition",
+          "expectedResult": "Cause classified",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Chosen repair/wait/escalate path documented"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": [
+        "unresolved-relationship"
+      ]
+    },
+    {
+      "summary": "Load composition for a subject the UI will render.",
+      "why": "UIs need the bag of content instances, not only raw.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "composition"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "composition"
+      ],
+      "id": "compose-subject-ui",
+      "type": "guide",
+      "title": "Compose same-subject content for a UI",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "compose",
+          "title": "Request same-subject composition",
+          "expectedResult": "Composed payload",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Expected content types present"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Read employees and contractors through People bindings.",
+      "why": "Abstract projection avoids hand-merged lists.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [
+        "inspect-effective-metadata"
+      ],
+      "related": [
+        "people-union"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "abstracts"
+      ],
+      "id": "query-people-abstract",
+      "type": "guide",
+      "title": "Query the People abstract view",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "query",
+          "title": "Query People abstract",
+          "expectedResult": "Mixed concrete types under People",
+          "optional": false
+        }
+      ],
+      "verification": [
+        "Bindings explain each member"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    },
+    {
+      "summary": "Record analysis, then a distinct decision.",
+      "why": "Keeping them separate preserves auditability.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "analysis-objects",
+        "decisions-content"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [
+        "workflow"
+      ],
+      "id": "evidence-to-decision",
+      "type": "guide",
+      "title": "Move from evidence to analysis and a decision",
+      "useWhen": [],
+      "doNotUseWhen": [],
+      "inputs": [],
+      "permissions": [],
+      "steps": [
+        {
+          "id": "analysis",
+          "title": "Create analysis from evidence",
+          "expectedResult": "Analysis object",
+          "optional": false
+        },
+        {
+          "id": "decision",
+          "title": "Record decision",
+          "expectedResult": "Decision object",
+          "optional": false,
+          "confirmationRequired": true
+        }
+      ],
+      "verification": [
+        "Decision references analysis"
+      ],
+      "recovery": [],
+      "tutorialIds": [],
+      "referenceIds": [],
+      "scenarioIds": []
+    }
+  ],
+  "scenarios": [
+    {
+      "summary": "Detected organization/agent scope differs from the task.",
+      "audiences": [
+        "builders",
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Do not write while scope is wrong"
+      ],
+      "alternatives": [],
+      "tags": [],
+      "id": "scope-mismatch",
+      "type": "scenario",
+      "title": "Scope does not match the intended workspace",
+      "situation": "Studio or API session is scoped to a different org/agent than intended.",
+      "preconditions": [],
+      "signals": [
+        "Wrong org label",
+        "Unexpected agent inheritance set"
+      ],
+      "decisionQuestion": "Apply a different scope or stop?",
+      "paths": [
+        {
+          "id": "reapply",
+          "label": "Apply correct scope",
+          "when": "You can select the intended org/agent",
+          "rationale": "Isolation is restored before any mutation.",
+          "guideIds": [
+            "apply-scope"
+          ]
+        },
+        {
+          "id": "stop",
+          "label": "Stop",
+          "when": "Correct scope is unavailable or unauthorized",
+          "rationale": "Escalate rather than act in the wrong workspace.",
+          "guideIds": [],
+          "confirmationRequired": true
+        }
+      ],
+      "verification": [
+        "Subsequent operations show the intended scope"
+      ],
+      "recovery": [],
+      "escalation": "Ask an operator for access to the intended workspace."
+    },
+    {
+      "summary": "PATCH/PUT rejected because expected revision was stale.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Conflict means the prior write did not apply"
+      ],
+      "alternatives": [],
+      "tags": [],
+      "id": "stale-revision-conflict",
+      "type": "scenario",
+      "title": "A write returns a stale-revision conflict",
+      "situation": "API returned a revision conflict; record unchanged.",
+      "preconditions": [],
+      "signals": [
+        "409/conflict",
+        "expectedRevision mismatch"
+      ],
+      "decisionQuestion": "Reapply from current revision or escalate?",
+      "paths": [
+        {
+          "id": "retry",
+          "label": "Reload and retry",
+          "when": "Intended change still valid against current meaning",
+          "rationale": "Safe recovery path.",
+          "guideIds": [
+            "reload-retry-conflict"
+          ]
+        },
+        {
+          "id": "escalate",
+          "label": "Escalate",
+          "when": "Current meaning changed in a conflicting way",
+          "guideIds": [],
+          "confirmationRequired": true
+        }
+      ],
+      "verification": [
+        "No forced overwrite without compare"
+      ],
+      "recovery": [
+        "Use reload-retry-conflict guide"
+      ]
+    },
+    {
+      "summary": "Traversal returns an unresolved target marker.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Do not hide unresolved targets"
+      ],
+      "alternatives": [],
+      "tags": [],
+      "id": "unresolved-relationship",
+      "type": "scenario",
+      "title": "A relationship target is unresolved",
+      "situation": "Related record cannot be resolved under the active definition.",
+      "preconditions": [],
+      "signals": [],
+      "decisionQuestion": "Repair, wait, or preserve/escalate?",
+      "paths": [
+        {
+          "id": "repair",
+          "label": "Repair target",
+          "when": "Target should exist and can be created/linked",
+          "guideIds": [
+            "diagnose-unresolved",
+            "define-traverse-relationship"
+          ]
+        },
+        {
+          "id": "preserve",
+          "label": "Preserve unresolved",
+          "when": "Unresolved is intentional",
+          "guideIds": [
+            "diagnose-unresolved"
+          ]
+        }
+      ],
+      "verification": [
+        "Chosen path matches authored relationship semantics"
+      ],
+      "recovery": []
+    },
+    {
+      "summary": "Validation succeeded; runtime still on previous effective metadata.",
+      "audiences": [
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [
+        "Intelligence proposals never auto-install"
+      ],
+      "alternatives": [],
+      "tags": [],
+      "id": "pack-valid-not-installed",
+      "type": "scenario",
+      "title": "A metadata pack is valid but not installed",
+      "situation": "Validate passed; install not confirmed.",
+      "preconditions": [],
+      "signals": [],
+      "decisionQuestion": "Explicitly install or cancel?",
+      "paths": [
+        {
+          "id": "install",
+          "label": "Install",
+          "when": "Change is reviewed and approved",
+          "guideIds": [
+            "validate-install-pack"
+          ],
+          "confirmationRequired": true
+        },
+        {
+          "id": "cancel",
+          "label": "Cancel",
+          "when": "Not ready to change runtime",
+          "rationale": "Validation alone must leave runtime unchanged.",
+          "guideIds": []
+        }
+      ],
+      "verification": [
+        "Cancel leaves effective metadata unchanged"
+      ],
+      "recovery": []
+    },
+    {
+      "summary": "Choose raw, composition, or abstract based on fidelity needs.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "choose-subject-view",
+      "type": "scenario",
+      "title": "A caller needs a subject view",
+      "situation": "UI or API caller needs subject data and is unsure which access method to use.",
+      "preconditions": [],
+      "signals": [],
+      "decisionQuestion": "Raw, composed, or abstract?",
+      "paths": [
+        {
+          "id": "raw",
+          "label": "Raw",
+          "when": "Need original payload/envelope fidelity",
+          "guideIds": [
+            "choose-access-method"
+          ]
+        },
+        {
+          "id": "composed",
+          "label": "Composition",
+          "when": "Need same-subject content instances for a UI",
+          "guideIds": [
+            "compose-subject-ui"
+          ]
+        },
+        {
+          "id": "abstract",
+          "label": "Abstract",
+          "when": "Need a projected union such as People",
+          "guideIds": [
+            "query-people-abstract"
+          ]
+        }
+      ],
+      "verification": [
+        "Returned shape matches the caller goal"
+      ],
+      "recovery": []
+    },
+    {
+      "summary": "Choose forward/inverse and expanded/unexpanded handling.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "traversal-direction",
+      "type": "scenario",
+      "title": "Relationship traversal direction and expansion",
+      "situation": "Caller must traverse a relationship and pick direction/expansion.",
+      "preconditions": [],
+      "signals": [],
+      "decisionQuestion": "Which direction and expansion?",
+      "paths": [
+        {
+          "id": "forward",
+          "label": "Forward",
+          "when": "Following the definition's forward semantics",
+          "guideIds": [
+            "define-traverse-relationship"
+          ]
+        },
+        {
+          "id": "inverse",
+          "label": "Inverse",
+          "when": "Need inbound links",
+          "guideIds": [
+            "define-traverse-relationship"
+          ]
+        }
+      ],
+      "verification": [
+        "Results match definition direction"
+      ],
+      "recovery": []
+    }
+  ],
+  "decisions": [],
+  "glossary": [
+    {
+      "id": "agent",
+      "term": "Agent",
+      "meaning": "An inheritance and configuration unit inside an organization.",
+      "technicalName": "agent",
+      "aliases": [],
+      "relatedConceptIds": [
+        "agents-inheritance"
+      ]
+    },
+    {
+      "id": "scope",
+      "term": "Scope",
+      "meaning": "Selected organization and agent context for reads and writes.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "org-agent-scope"
+      ]
+    },
+    {
+      "id": "source",
+      "term": "Source",
+      "meaning": "Origin that feeds content into Memory.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "sources-and-memory"
+      ]
+    },
+    {
+      "id": "memory",
+      "term": "Memory",
+      "meaning": "Durable store of Memorix records.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "sources-and-memory"
+      ]
+    },
+    {
+      "id": "object-type",
+      "term": "Object type",
+      "meaning": "Identity kind for a record subject.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "object-content-category"
+      ]
+    },
+    {
+      "id": "content-type",
+      "term": "Content type",
+      "meaning": "Shape of a content instance on a subject.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "object-content-category"
+      ]
+    },
+    {
+      "id": "data-category",
+      "term": "Data category",
+      "meaning": "Category axis distinct from object and content type.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "object-content-category"
+      ]
+    },
+    {
+      "id": "abstract",
+      "term": "Abstract",
+      "meaning": "Virtual projected union over concrete types via bindings.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "abstracts-bindings"
+      ]
+    },
+    {
+      "id": "binding",
+      "term": "Binding",
+      "meaning": "Maps concrete members into an abstract.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "abstracts-bindings"
+      ]
+    },
+    {
+      "id": "effective-metadata",
+      "term": "Effective metadata",
+      "meaning": "Resolved definitions after inheritance and installation.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "effective-metadata"
+      ]
+    },
+    {
+      "id": "mapping",
+      "term": "Mapping",
+      "meaning": "Declared transform from source shape to Memory content.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "mappings-transforms"
+      ]
+    },
+    {
+      "id": "composition",
+      "term": "Composition",
+      "meaning": "Explicit same-subject aggregation of content instances.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "composition"
+      ]
+    },
+    {
+      "id": "relationship-definition",
+      "term": "Relationship definition",
+      "meaning": "Metadata describing an allowed relationship kind.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "relationship-definitions"
+      ]
+    },
+    {
+      "id": "relationship-reference",
+      "term": "Relationship reference",
+      "meaning": "Stored link instance on a record.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "relationship-references"
+      ]
+    },
+    {
+      "id": "traversal",
+      "term": "Traversal",
+      "meaning": "Forward or inverse walk of relationship references.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "traversal"
+      ]
+    },
+    {
+      "id": "revision",
+      "term": "Revision",
+      "meaning": "Optimistic concurrency token on a record.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "record-revisions"
+      ]
+    },
+    {
+      "id": "analysis",
+      "term": "Analysis",
+      "meaning": "Evaluated evidence content distinct from a decision.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "analysis-objects"
+      ]
+    },
+    {
+      "id": "decision",
+      "term": "Decision",
+      "meaning": "Committed choice recorded separately from analysis.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "decisions-content"
+      ]
+    },
+    {
+      "id": "intelligence-proposal",
+      "term": "Intelligence proposal",
+      "meaning": "Suggested change that never auto-installs.",
+      "aliases": [],
+      "relatedConceptIds": [
+        "intelligence-proposals"
+      ]
+    }
+  ],
+  "visuals": [
+    {
+      "id": "scope-apply",
+      "src": "images/scope-apply.png",
+      "alt": "Studio scope selector with organization and agent chosen before Apply scope",
+      "caption": "Scope must be applied explicitly before work begins.",
+      "conceptIds": [
+        "org-agent-scope"
+      ],
+      "guideIds": [],
+      "whatToNotice": [
+        "Organization and agent are named",
+        "Apply scope is a deliberate action",
+        "Scope is not decorative chrome"
+      ],
+      "whyItMatters": "Wrong scope risks cross-workspace writes.",
+      "clientId": "memorix-studio",
+      "screenId": "scope",
+      "flowId": "apply-scope"
+    },
+    {
+      "id": "revision-conflict",
+      "src": "images/revision-conflict.png",
+      "alt": "Conflict dialog showing stale expected revision while record remains unchanged",
+      "caption": "Stale writers are rejected; the record stays at the newer revision.",
+      "conceptIds": [
+        "record-revisions"
+      ],
+      "guideIds": [],
+      "whatToNotice": [
+        "Expected revision is shown",
+        "Record was not mutated",
+        "Recovery is reload and retry"
+      ],
+      "whyItMatters": "Revision preconditions preserve newer data.",
+      "clientId": "memorix-studio",
+      "screenId": "workflow",
+      "flowId": "handle-revision-conflict"
+    }
+  ],
+  "diagrams": [
+    {
+      "id": "memorix-central-journey",
+      "type": "journey",
+      "title": "Memorix central product journey",
+      "summary": "Conceptual path from scope through metadata, records, relationships, analysis, and decisions.",
+      "why": "Orients every concept page in the same mental model.",
+      "nodes": [
+        {
+          "id": "scope",
+          "label": "Scope",
+          "conceptId": "org-agent-scope"
+        },
+        {
+          "id": "metadata",
+          "label": "Explicit metadata",
+          "conceptId": "explicit-metadata-installation"
+        },
+        {
+          "id": "effective",
+          "label": "Effective model",
+          "conceptId": "effective-metadata"
+        },
+        {
+          "id": "raw",
+          "label": "Raw/concrete",
+          "conceptId": "raw-records"
+        },
+        {
+          "id": "compose",
+          "label": "Composition/abstracts",
+          "conceptId": "composition"
+        },
+        {
+          "id": "rels",
+          "label": "Relationships",
+          "conceptId": "relationship-definitions"
+        },
+        {
+          "id": "analysis",
+          "label": "Analysis",
+          "conceptId": "analysis-objects"
+        },
+        {
+          "id": "decisions",
+          "label": "Decisions",
+          "conceptId": "decisions-content"
+        }
+      ],
+      "edges": [
+        {
+          "from": "scope",
+          "to": "metadata",
+          "label": "select"
+        },
+        {
+          "from": "metadata",
+          "to": "effective",
+          "label": "install/resolve"
+        },
+        {
+          "from": "effective",
+          "to": "raw",
+          "label": "shape data"
+        },
+        {
+          "from": "raw",
+          "to": "compose",
+          "label": "project"
+        },
+        {
+          "from": "compose",
+          "to": "rels",
+          "label": "link"
+        },
+        {
+          "from": "rels",
+          "to": "analysis",
+          "label": "evaluate"
+        },
+        {
+          "from": "analysis",
+          "to": "decisions",
+          "label": "commit"
+        }
+      ],
+      "howToRead": "Left to right is conceptual learning order — not an auto-discovered runtime trace.",
+      "keyTakeaways": [
+        "Conceptual journey",
+        "Each stage links to concepts",
+        "Not a discovered trace"
+      ],
+      "textAlternative": "Scope leads to explicit metadata and an effective model, then to concrete/raw data, composition and abstracts, relationships, analysis, and decisions/operation.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "related": [],
+      "tags": [
+        "overview"
+      ]
+    },
+    {
+      "id": "agent-inheritance",
+      "type": "hierarchy",
+      "title": "Agent inheritance",
+      "summary": "Parent and child agents resolve into effective definitions.",
+      "why": "Explains why Studio shows effective results, not only local files.",
+      "nodes": [
+        {
+          "id": "parent",
+          "label": "Parent agent",
+          "conceptId": "agents-inheritance"
+        },
+        {
+          "id": "child",
+          "label": "Child agent",
+          "conceptId": "agents-inheritance"
+        },
+        {
+          "id": "effective",
+          "label": "Effective definitions",
+          "conceptId": "effective-metadata"
+        }
+      ],
+      "edges": [
+        {
+          "from": "parent",
+          "to": "child",
+          "label": "inherit"
+        },
+        {
+          "from": "child",
+          "to": "effective",
+          "label": "resolve"
+        }
+      ],
+      "howToRead": "Parents contribute first; children may replace or add.",
+      "keyTakeaways": [],
+      "textAlternative": "Parent agent definitions flow to a child agent; the effective model is what runtime uses after resolution.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    },
+    {
+      "id": "metadata-lifecycle",
+      "type": "flow",
+      "title": "Metadata lifecycle",
+      "summary": "Pack → validate → explicit install → effective resolution → runtime; proposals stay off the auto path.",
+      "why": "Separates proposal, approval, installation, and use.",
+      "nodes": [
+        {
+          "id": "pack",
+          "label": "Pack",
+          "conceptId": "explicit-metadata-installation"
+        },
+        {
+          "id": "validate",
+          "label": "Validate"
+        },
+        {
+          "id": "install",
+          "label": "Explicit install"
+        },
+        {
+          "id": "effective",
+          "label": "Effective",
+          "conceptId": "effective-metadata"
+        },
+        {
+          "id": "runtime",
+          "label": "Runtime"
+        },
+        {
+          "id": "proposal",
+          "label": "Intelligence proposal",
+          "conceptId": "intelligence-proposals"
+        }
+      ],
+      "edges": [
+        {
+          "from": "pack",
+          "to": "validate",
+          "label": "check"
+        },
+        {
+          "from": "validate",
+          "to": "install",
+          "label": "confirm"
+        },
+        {
+          "from": "install",
+          "to": "effective",
+          "label": "resolve"
+        },
+        {
+          "from": "effective",
+          "to": "runtime",
+          "label": "use"
+        },
+        {
+          "from": "proposal",
+          "to": "validate",
+          "label": "review only"
+        }
+      ],
+      "howToRead": "Follow the solid path; proposals branch and never auto-join install.",
+      "keyTakeaways": [],
+      "textAlternative": "A metadata pack is validated, then explicitly installed, resolved into the effective model, and consumed at runtime. Intelligence proposals require a separate explicit install path and never auto-install.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    },
+    {
+      "id": "record-content-model",
+      "type": "entity-relationship",
+      "title": "Record and content model",
+      "summary": "Record identity relates to object type, content type, category, raw, snapshots, and composition.",
+      "why": "Keeps identity and payload axes distinct.",
+      "nodes": [
+        {
+          "id": "record",
+          "label": "Record identity",
+          "conceptId": "raw-records"
+        },
+        {
+          "id": "object",
+          "label": "Object type",
+          "conceptId": "object-content-category"
+        },
+        {
+          "id": "content",
+          "label": "Content type"
+        },
+        {
+          "id": "category",
+          "label": "Data category"
+        },
+        {
+          "id": "raw",
+          "label": "Raw"
+        },
+        {
+          "id": "snap",
+          "label": "Snapshot"
+        },
+        {
+          "id": "compose",
+          "label": "Composition",
+          "conceptId": "composition"
+        }
+      ],
+      "edges": [
+        {
+          "from": "record",
+          "to": "object"
+        },
+        {
+          "from": "record",
+          "to": "content"
+        },
+        {
+          "from": "record",
+          "to": "category"
+        },
+        {
+          "from": "record",
+          "to": "raw"
+        },
+        {
+          "from": "record",
+          "to": "snap"
+        },
+        {
+          "from": "raw",
+          "to": "compose"
+        },
+        {
+          "from": "snap",
+          "to": "compose"
+        }
+      ],
+      "howToRead": "Center on the record; spokes are model axes and views.",
+      "keyTakeaways": [],
+      "textAlternative": "A record identity has an object type, content type, and data category. Raw content and snapshots are content instances that can be composed for the same subject.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    },
+    {
+      "id": "people-union-diagram",
+      "type": "relationship-map",
+      "title": "People abstract union",
+      "summary": "Employees and contractors bind into the People abstract projection.",
+      "why": "Shows virtual union without stored merged rows.",
+      "nodes": [
+        {
+          "id": "employees",
+          "label": "employees"
+        },
+        {
+          "id": "contractors",
+          "label": "contractors"
+        },
+        {
+          "id": "bindings",
+          "label": "Bindings",
+          "conceptId": "abstracts-bindings"
+        },
+        {
+          "id": "people",
+          "label": "People",
+          "conceptId": "people-union"
+        }
+      ],
+      "edges": [
+        {
+          "from": "employees",
+          "to": "bindings"
+        },
+        {
+          "from": "contractors",
+          "to": "bindings"
+        },
+        {
+          "from": "bindings",
+          "to": "people",
+          "label": "project"
+        }
+      ],
+      "howToRead": "Concrete types feed bindings into People.",
+      "keyTakeaways": [],
+      "textAlternative": "Employees and contractors are bound into the People abstract. Combined reads return concrete members under the People projection.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    },
+    {
+      "id": "relationship-traversal",
+      "type": "flow",
+      "title": "Relationship definition to traversal",
+      "summary": "Definition versus stored reference; forward/inverse; resolved versus unresolved.",
+      "why": "Prevents treating definitions as edges.",
+      "nodes": [
+        {
+          "id": "def",
+          "label": "Definition",
+          "conceptId": "relationship-definitions"
+        },
+        {
+          "id": "ref",
+          "label": "Stored ref",
+          "conceptId": "relationship-references"
+        },
+        {
+          "id": "fwd",
+          "label": "Forward",
+          "conceptId": "traversal"
+        },
+        {
+          "id": "inv",
+          "label": "Inverse"
+        },
+        {
+          "id": "resolved",
+          "label": "Resolved",
+          "conceptId": "resolved-unresolved"
+        },
+        {
+          "id": "unresolved",
+          "label": "Unresolved"
+        }
+      ],
+      "edges": [
+        {
+          "from": "def",
+          "to": "ref"
+        },
+        {
+          "from": "ref",
+          "to": "fwd"
+        },
+        {
+          "from": "ref",
+          "to": "inv"
+        },
+        {
+          "from": "fwd",
+          "to": "resolved"
+        },
+        {
+          "from": "fwd",
+          "to": "unresolved"
+        }
+      ],
+      "howToRead": "Definition enables references; traversal yields resolved or unresolved targets.",
+      "keyTakeaways": [],
+      "textAlternative": "A relationship definition enables stored references. Traversal may go forward or inverse and can return resolved or unresolved targets.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    },
+    {
+      "id": "revision-safe-write",
+      "type": "state",
+      "title": "Revision-safe write flow",
+      "summary": "Load, write with expected revision, success or conflict with reload/retry.",
+      "why": "Makes stale-write recovery explicit.",
+      "nodes": [
+        {
+          "id": "load",
+          "label": "Load",
+          "conceptId": "record-revisions"
+        },
+        {
+          "id": "write",
+          "label": "Write + expected rev"
+        },
+        {
+          "id": "ok",
+          "label": "Success"
+        },
+        {
+          "id": "conflict",
+          "label": "Conflict"
+        },
+        {
+          "id": "reload",
+          "label": "Reload/retry"
+        }
+      ],
+      "edges": [
+        {
+          "from": "load",
+          "to": "write"
+        },
+        {
+          "from": "write",
+          "to": "ok",
+          "label": "match"
+        },
+        {
+          "from": "write",
+          "to": "conflict",
+          "label": "stale"
+        },
+        {
+          "from": "conflict",
+          "to": "reload"
+        },
+        {
+          "from": "reload",
+          "to": "write"
+        }
+      ],
+      "howToRead": "Conflict path returns to reload; success updates revision.",
+      "keyTakeaways": [],
+      "textAlternative": "Load a record and its revision. Write with that expected revision. On success the revision advances. On conflict, reload and retry or escalate; the record was not changed by the failed write.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    },
+    {
+      "id": "intelligence-journey",
+      "type": "flow",
+      "title": "Intelligence journey",
+      "summary": "Evidence can yield analysis, decision, and proposals that still require explicit install.",
+      "why": "Keeps human confirmation on runtime-changing actions.",
+      "nodes": [
+        {
+          "id": "evidence",
+          "label": "Evidence"
+        },
+        {
+          "id": "analysis",
+          "label": "Analysis",
+          "conceptId": "analysis-objects"
+        },
+        {
+          "id": "decision",
+          "label": "Decision",
+          "conceptId": "decisions-content"
+        },
+        {
+          "id": "proposal",
+          "label": "Proposal",
+          "conceptId": "intelligence-proposals"
+        },
+        {
+          "id": "install",
+          "label": "Explicit action",
+          "conceptId": "explicit-metadata-installation"
+        }
+      ],
+      "edges": [
+        {
+          "from": "evidence",
+          "to": "analysis"
+        },
+        {
+          "from": "analysis",
+          "to": "decision"
+        },
+        {
+          "from": "decision",
+          "to": "proposal"
+        },
+        {
+          "from": "proposal",
+          "to": "install",
+          "label": "confirm"
+        }
+      ],
+      "howToRead": "Proposals do not skip the install confirmation gate.",
+      "keyTakeaways": [],
+      "textAlternative": "Source and content evidence can produce analysis and a decision. An intelligence proposal may follow but requires explicit human-controlled installation or operational action.",
+      "audiences": [],
+      "related": [],
+      "tags": []
+    }
+  ],
+  "relationships": [
+    {
+      "id": "scope-prereq-effective",
+      "type": "prerequisiteOf",
+      "from": "org-agent-scope",
+      "to": "effective-metadata"
+    },
+    {
+      "id": "install-explains-proposals",
+      "type": "explains",
+      "from": "explicit-metadata-installation",
+      "to": "intelligence-proposals"
+    },
+    {
+      "id": "people-part-of-abstracts",
+      "type": "partOf",
+      "from": "people-union",
+      "to": "abstracts-bindings"
+    }
+  ],
+  "tutorials": [
+    {
+      "summary": "Load the synthetic dataset and confirm scope.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "org-agent-scope"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "start-with-sample-data",
+      "type": "tutorial",
+      "title": "Start Memorix with the sample dataset",
+      "requiredServices": [],
+      "datasetId": "memorix-synthetic-basic",
+      "setup": [
+        "Start local Memorix stack",
+        "Load sample dataset"
+      ],
+      "steps": [
+        {
+          "id": "scope",
+          "kind": "ui",
+          "title": "Apply demo scope",
+          "expected": "Scope applied"
+        },
+        {
+          "id": "verify",
+          "kind": "verification",
+          "title": "List sample subjects",
+          "expected": "Stable fictional IDs visible"
+        }
+      ],
+      "verification": [
+        "Sample entities listed"
+      ],
+      "reset": [
+        "Reset sample dataset"
+      ],
+      "troubleshooting": [],
+      "runnable": false
+    },
+    {
+      "summary": "Practice expected-revision writes on sample data.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "record-revisions"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "first-revision-safe-record",
+      "type": "tutorial",
+      "title": "Read and write the first revision-safe record",
+      "requiredServices": [],
+      "datasetId": "memorix-synthetic-basic",
+      "setup": [],
+      "steps": [
+        {
+          "id": "read",
+          "kind": "api",
+          "title": "Read record",
+          "expected": "Revision present"
+        },
+        {
+          "id": "write",
+          "kind": "api",
+          "title": "Write with expected revision",
+          "expected": "Success"
+        }
+      ],
+      "verification": [
+        "Revision advanced"
+      ],
+      "reset": [
+        "Restore sample record"
+      ],
+      "troubleshooting": [],
+      "runnable": false
+    },
+    {
+      "summary": "See fidelity differences on the same subjects.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "composition",
+        "people-union"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "compare-views",
+      "type": "tutorial",
+      "title": "Compare raw, composed, and abstract views",
+      "requiredServices": [],
+      "datasetId": "memorix-synthetic-basic",
+      "setup": [],
+      "steps": [
+        {
+          "id": "raw",
+          "kind": "ui",
+          "title": "Open raw",
+          "expected": "Envelope + raw"
+        },
+        {
+          "id": "compose",
+          "kind": "ui",
+          "title": "Open composition",
+          "expected": "Multiple instances"
+        },
+        {
+          "id": "people",
+          "kind": "ui",
+          "title": "Open People",
+          "expected": "Union projection"
+        }
+      ],
+      "verification": [
+        "Each view explained"
+      ],
+      "reset": [],
+      "troubleshooting": [],
+      "runnable": false
+    },
+    {
+      "summary": "Hands-on relationship definition and traversal.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "traversal"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "relationships-lab",
+      "type": "tutorial",
+      "title": "Define, store, and traverse relationships",
+      "requiredServices": [],
+      "datasetId": "memorix-synthetic-basic",
+      "setup": [],
+      "steps": [
+        {
+          "id": "def",
+          "kind": "explanation",
+          "title": "Review definition",
+          "body": "Use sample relationship definition."
+        },
+        {
+          "id": "traverse",
+          "kind": "api",
+          "title": "Traverse forward and inverse",
+          "expected": "Resolved and unresolved cases"
+        }
+      ],
+      "verification": [
+        "Unresolved retained"
+      ],
+      "reset": [],
+      "troubleshooting": [],
+      "runnable": false
+    },
+    {
+      "summary": "Trigger and recover from a conflict using sample data.",
+      "audiences": [
+        "developers"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "record-revisions"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "conflict-lab",
+      "type": "tutorial",
+      "title": "Recover from a stale revision conflict",
+      "requiredServices": [],
+      "datasetId": "memorix-synthetic-basic",
+      "setup": [],
+      "steps": [
+        {
+          "id": "stale",
+          "kind": "api",
+          "title": "Submit stale revision",
+          "expected": "Conflict"
+        },
+        {
+          "id": "retry",
+          "kind": "api",
+          "title": "Reload and retry",
+          "expected": "Success"
+        }
+      ],
+      "verification": [
+        "Record unchanged by failed write"
+      ],
+      "reset": [],
+      "troubleshooting": [],
+      "runnable": false
+    },
+    {
+      "summary": "Practice validation versus confirmation.",
+      "audiences": [
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "explicit-metadata-installation"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "install-pack-lab",
+      "type": "tutorial",
+      "title": "Validate and explicitly install a metadata pack",
+      "requiredServices": [],
+      "setup": [],
+      "steps": [
+        {
+          "id": "validate",
+          "kind": "ui",
+          "title": "Validate",
+          "expected": "Valid"
+        },
+        {
+          "id": "cancel",
+          "kind": "ui",
+          "title": "Cancel once",
+          "expected": "Runtime unchanged"
+        },
+        {
+          "id": "install",
+          "kind": "ui",
+          "title": "Confirm install",
+          "expected": "Effective updated"
+        }
+      ],
+      "verification": [
+        "Cancel path proven"
+      ],
+      "reset": [],
+      "troubleshooting": [],
+      "runnable": false
+    },
+    {
+      "summary": "Create analysis then a distinct decision on sample evidence.",
+      "audiences": [
+        "developers",
+        "builders"
+      ],
+      "whenItMatters": [],
+      "whenNotToUse": [],
+      "prerequisites": [],
+      "related": [
+        "analysis-objects",
+        "decisions-content"
+      ],
+      "next": [],
+      "exampleIds": [],
+      "commonMistakes": [],
+      "successCriteria": [],
+      "invariants": [],
+      "alternatives": [],
+      "tags": [],
+      "id": "analysis-decision-lab",
+      "type": "tutorial",
+      "title": "Move from records to analysis and a decision",
+      "requiredServices": [],
+      "datasetId": "memorix-synthetic-basic",
+      "setup": [],
+      "steps": [
+        {
+          "id": "analysis",
+          "kind": "api",
+          "title": "Write analysis",
+          "expected": "Analysis stored"
+        },
+        {
+          "id": "decision",
+          "kind": "api",
+          "title": "Write decision",
+          "expected": "Decision stored"
+        }
+      ],
+      "verification": [
+        "Types remain distinct"
+      ],
+      "reset": [],
+      "troubleshooting": [],
+      "runnable": false
+    }
+  ],
+  "examples": [
+    {
+      "id": "memorix-record-envelope",
+      "type": "record",
+      "title": "memorix-record/2 envelope",
+      "purpose": "Show identity, revision, and content envelope fields.",
+      "explanation": "Envelope metadata is distinct from product payload.",
+      "audiences": [
+        "developers"
+      ],
+      "datasetId": "memorix-synthetic-basic",
+      "conceptIds": [
+        "raw-records",
+        "record-revisions"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "revision-safe-write",
+      "type": "api",
+      "title": "Revision-safe write",
+      "purpose": "Write with expected revision.",
+      "audiences": [
+        "developers"
+      ],
+      "conceptIds": [
+        "record-revisions"
+      ],
+      "operationIds": [
+        "patch-record"
+      ]
+    },
+    {
+      "id": "revision-conflict-response",
+      "type": "error",
+      "title": "Revision conflict response and retry",
+      "purpose": "Show conflict payload and retry input.",
+      "audiences": [
+        "developers"
+      ],
+      "conceptIds": [
+        "record-revisions"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "raw-vs-composed",
+      "type": "api",
+      "title": "Raw versus composed subject responses",
+      "purpose": "Compare fidelity of raw and composition.",
+      "audiences": [],
+      "conceptIds": [
+        "raw-records",
+        "composition"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "people-abstract-query",
+      "type": "api",
+      "title": "People abstract query/result",
+      "purpose": "Demonstrate union projection.",
+      "audiences": [],
+      "conceptIds": [
+        "people-union"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "relationship-def-and-ref",
+      "type": "record",
+      "title": "Relationship definition and stored reference",
+      "purpose": "Contrast metadata definition with stored ref.",
+      "audiences": [],
+      "conceptIds": [
+        "relationship-definitions",
+        "relationship-references"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "traversal-resolved-unresolved",
+      "type": "api",
+      "title": "Forward/inverse traversal with resolved and unresolved targets",
+      "purpose": "Show both target states.",
+      "audiences": [],
+      "conceptIds": [
+        "traversal",
+        "resolved-unresolved"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "metadata-pack-install",
+      "type": "ui",
+      "title": "Metadata-pack validation and explicit installation",
+      "purpose": "Evidence that validate ≠ install.",
+      "audiences": [],
+      "conceptIds": [
+        "explicit-metadata-installation"
+      ],
+      "operationIds": []
+    },
+    {
+      "id": "analysis-decision-records",
+      "type": "record",
+      "title": "Analysis and decision records",
+      "purpose": "Keep analysis and decision content types distinct.",
+      "audiences": [],
+      "conceptIds": [
+        "analysis-objects",
+        "decisions-content"
+      ],
+      "operationIds": []
+    }
+  ],
+  "sampleData": [
+    {
+      "id": "memorix-synthetic-basic",
+      "version": "1.0.0",
+      "purpose": "Deterministic synthetic Memorix subjects for docs, screenshots, and tutorials.",
+      "files": [
+        "files/README.md"
+      ],
+      "schemas": [],
+      "seedInstructions": "Load the synthetic fixture pack into a local Memorix workspace reserved for docs.",
+      "resetInstructions": "Re-seed the fixture pack; do not use production data.",
+      "entities": [
+        "employee-e1",
+        "contractor-c1",
+        "work-item-w1",
+        "procedure-p1",
+        "analysis-a1",
+        "decision-d1"
+      ],
+      "expectedRelationships": [
+        "employee-e1 reports-to unresolved-manager",
+        "work-item-w1 assigned-to employee-e1"
+      ],
+      "sensitivity": "public",
+      "origin": "synthetic"
+    }
+  ],
+  "uiClients": [
+    {
+      "id": "memorix-studio",
+      "title": "Memorix Studio",
+      "summary": "Service-oriented UI for designing, operating, and exploring Memorix.",
+      "audiences": [
+        "builders",
+        "developers"
+      ],
+      "baseUrl": "http://127.0.0.1:4173",
+      "screenIds": [
+        "scope",
+        "agents",
+        "raw-records",
+        "composition",
+        "abstracts",
+        "relationships",
+        "workflow"
+      ],
+      "flowIds": [
+        "apply-scope",
+        "inspect-effective-metadata",
+        "load-raw",
+        "load-composition",
+        "query-abstract",
+        "traverse-relationship",
+        "handle-unresolved",
+        "handle-revision-conflict",
+        "validate-install-metadata"
+      ],
+      "screens": [
+        {
+          "id": "scope",
+          "title": "Scope selector",
+          "route": "/",
+          "purpose": "Choose organization and agent scope.",
+          "audiences": [
+            "builders"
+          ],
+          "prerequisites": [],
+          "controls": [],
+          "states": [
+            "empty",
+            "selected",
+            "applied"
+          ],
+          "screenshotIds": [],
+          "conceptIds": [
+            "org-agent-scope"
+          ],
+          "operationIds": [],
+          "next": []
+        },
+        {
+          "id": "workflow",
+          "title": "Workflow explorer",
+          "route": "/explore/workflow",
+          "purpose": "Inspect workflow records and conflicts.",
+          "audiences": [],
+          "prerequisites": [],
+          "controls": [],
+          "states": [
+            "loading",
+            "success",
+            "conflict"
+          ],
+          "screenshotIds": [],
+          "conceptIds": [
+            "record-revisions"
+          ],
+          "operationIds": [],
+          "next": []
+        }
+      ],
+      "flows": [
+        {
+          "id": "apply-scope",
+          "title": "Apply scope",
+          "goal": "Lock the intended workspace.",
+          "steps": [
+            {
+              "id": "select",
+              "action": "Select org and agent",
+              "expectedState": "Selected"
+            },
+            {
+              "id": "apply",
+              "action": "Apply scope",
+              "expectedState": "Applied"
+            }
+          ],
+          "operationIds": []
+        },
+        {
+          "id": "handle-revision-conflict",
+          "title": "Handle revision conflict",
+          "goal": "Recover from stale write.",
+          "steps": [
+            {
+              "id": "submit",
+              "action": "Submit stale update",
+              "expectedState": "conflict"
+            },
+            {
+              "id": "reload",
+              "action": "Reload and retry",
+              "expectedState": "success"
+            }
+          ],
+          "sampleDataId": "memorix-synthetic-basic",
+          "operationIds": []
+        },
+        {
+          "id": "validate-install-metadata",
+          "title": "Validate and explicitly install metadata",
+          "goal": "Install only after confirmation.",
+          "steps": [
+            {
+              "id": "validate",
+              "action": "Validate pack",
+              "expectedState": "valid"
+            },
+            {
+              "id": "confirm",
+              "action": "Confirm install",
+              "expectedState": "installed"
+            }
+          ],
+          "operationIds": []
+        }
+      ]
+    }
+  ],
+  "apis": [
+    {
+      "id": "memorix-records",
+      "title": "Memorix records API",
+      "summary": "Read and conditionally write Memorix records with revision preconditions.",
+      "why": "Agents and services need exact revision-safe operations.",
+      "audiences": [
+        "developers"
+      ],
+      "basePaths": [
+        "/api/records"
+      ],
+      "authExplanation": "Uses the product's configured auth; never embed secrets in docs.",
+      "operations": [
+        {
+          "id": "get-record",
+          "title": "Get record",
+          "summary": "Read a record envelope and content.",
+          "whenToUse": "Need current revision and payload",
+          "method": "GET",
+          "path": "/api/records/{id}",
+          "exampleIds": [],
+          "conceptIds": [
+            "raw-records",
+            "record-revisions"
+          ],
+          "guideIds": []
+        },
+        {
+          "id": "patch-record",
+          "title": "Patch record",
+          "summary": "Conditionally update a record with expected revision.",
+          "whenToUse": "Safe write",
+          "whenNotToUse": "When you do not know the current revision",
+          "method": "PATCH",
+          "path": "/api/records/{id}",
+          "exampleIds": [
+            "revision-safe-write"
+          ],
+          "conceptIds": [
+            "record-revisions"
+          ],
+          "guideIds": []
+        }
+      ],
+      "related": [
+        "record-revisions",
+        "first-revision-safe-write"
+      ]
+    }
+  ]
+}