@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/guides/evidence-to-decision.md

@@ -0,0 +1,25 @@
+---
+id: "evidence-to-decision"
+type: "guide"
+title: "Move from evidence to analysis and a decision"
+summary: "Record analysis, then a distinct decision."
+why: "Keeping them separate preserves auditability."
+audiences: ["developers", "builders"]
+related: ["analysis-objects", "decisions-content"]
+---
+# Move from evidence to analysis and a decision
+
+Record analysis, then a distinct decision.
+
+## Why this path
+
+Keeping them separate preserves auditability.
+
+## Steps
+
+1. **Create analysis from evidence** — Analysis object
+2. **Record decision** — Decision object
+
+## Verification
+
+- Decision references analysis

package/files/guides/first-revision-safe-write.md

@@ -0,0 +1,30 @@
+---
+id: "first-revision-safe-write"
+type: "guide"
+title: "Perform a first revision-safe read/write"
+summary: "Read a record, write with expected revision, verify."
+why: "Revision preconditions prevent lost updates."
+audiences: ["developers"]
+related: ["record-revisions"]
+invariants: ["Never omit expected revision on conditional writes"]
+---
+# Perform a first revision-safe read/write
+
+Read a record, write with expected revision, verify.
+
+## Why this path
+
+Revision preconditions prevent lost updates.
+
+## Invariants
+
+- Never omit expected revision on conditional writes
+
+## Steps
+
+1. **Read current record and revision** — Revision N known
+2. **Write with expected revision N** — Success or conflict
+
+## Verification
+
+- Record shows revision N+1 on success

package/files/guides/inspect-effective-metadata.md

@@ -0,0 +1,30 @@
+---
+id: "inspect-effective-metadata"
+type: "guide"
+title: "Inspect effective metadata before read/write"
+summary: "Confirm effective definitions before mutating records."
+why: "Source files alone may not match runtime."
+audiences: ["developers", "builders"]
+prerequisites: ["apply-scope"]
+related: ["effective-metadata"]
+invariants: ["Writes assume the effective model"]
+---
+# Inspect effective metadata before read/write
+
+Confirm effective definitions before mutating records.
+
+## Why this path
+
+Source files alone may not match runtime.
+
+## Invariants
+
+- Writes assume the effective model
+
+## Steps
+
+1. **Open effective metadata view** — Resolved definitions visible
+
+## Verification
+
+- Target object/content types appear as expected

package/files/guides/query-people-abstract.md

@@ -0,0 +1,25 @@
+---
+id: "query-people-abstract"
+type: "guide"
+title: "Query the People abstract view"
+summary: "Read employees and contractors through People bindings."
+why: "Abstract projection avoids hand-merged lists."
+audiences: ["developers", "builders"]
+prerequisites: ["inspect-effective-metadata"]
+related: ["people-union"]
+---
+# Query the People abstract view
+
+Read employees and contractors through People bindings.
+
+## Why this path
+
+Abstract projection avoids hand-merged lists.
+
+## Steps
+
+1. **Query People abstract** — Mixed concrete types under People
+
+## Verification
+
+- Bindings explain each member

package/files/guides/reload-retry-conflict.md

@@ -0,0 +1,32 @@
+---
+id: "reload-retry-conflict"
+type: "guide"
+title: "Reload, compare, and retry after a revision conflict"
+summary: "Recover safely when a stale write is rejected."
+why: "The record was not mutated; retry from current state."
+audiences: ["developers"]
+related: ["record-revisions"]
+invariants: ["Do not force overwrite without comparing meaning"]
+confirmationRequired: true
+---
+# Reload, compare, and retry after a revision conflict
+
+Recover safely when a stale write is rejected.
+
+## Why this path
+
+The record was not mutated; retry from current state.
+
+## Invariants
+
+- Do not force overwrite without comparing meaning
+
+## Steps
+
+1. **Reload current revision** — Fresh envelope
+2. **Compare intended change to current meaning** — Decision to reapply or escalate
+3. **Retry write with new expected revision** — Success or escalate
+
+## Verification
+
+- No silent overwrite of newer fields

package/files/guides/validate-install-pack.md

@@ -0,0 +1,32 @@
+---
+id: "validate-install-pack"
+type: "guide"
+title: "Validate and explicitly install a metadata pack"
+summary: "Validate first, then confirm installation."
+why: "Validation alone must not change runtime."
+audiences: ["builders", "developers"]
+related: ["explicit-metadata-installation"]
+invariants: ["Intelligence proposals never auto-install"]
+confirmationRequired: true
+---
+# Validate and explicitly install a metadata pack
+
+Validate first, then confirm installation.
+
+## Why this path
+
+Validation alone must not change runtime.
+
+## Invariants
+
+- Intelligence proposals never auto-install
+
+## Steps
+
+1. **Validate pack** — Validation report
+2. **Confirm install** — User confirms
+3. **Install pack** — Effective metadata updates
+
+## Verification
+
+- Effective metadata reflects the pack

package/files/indexes/books.json

@@ -0,0 +1,95 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "00-platform-overview",
+      "title": "Platform Overview",
+      "summary": "Surfaces, packages, hard rules, and where to start — developers and builders twins.",
+      "path": "books/00-platform-overview/"
+    },
+    {
+      "id": "01-format-for-dummies",
+      "title": "Format for Dummies",
+      "summary": "Mental model of the record envelope — OT/CT, composition, discriminators, and what is not stored on the record.",
+      "path": "books/01-format-for-dummies/"
+    },
+    {
+      "id": "02-runtime-data-client",
+      "title": "Runtime Data Client",
+      "summary": "Connection, scope, exact reads, writes, compose, abstracts, and client anti-patterns through Memorix Service / OpenAPI.",
+      "path": "books/02-runtime-data-client/"
+    },
+    {
+      "id": "03-lists-queries-pagination",
+      "title": "Lists, Queries, Pagination",
+      "summary": "List contracts, query grammar, cursors, page size, and multi-resource listing without foot-guns.",
+      "path": "books/03-lists-queries-pagination/"
+    },
+    {
+      "id": "04-data-access-patterns",
+      "title": "Data Access Patterns",
+      "summary": "Decision matrix — best / acceptable / forbidden access methods for real client tasks.",
+      "path": "books/04-data-access-patterns/"
+    },
+    {
+      "id": "05-metadata-agents-abstracts",
+      "title": "Metadata, Agents, Abstracts & Mappings",
+      "summary": "Agents, OT/CT, virtual abstracts, mappings, install/publish — never auto-install from intelligence.",
+      "path": "books/05-metadata-agents-abstracts/"
+    },
+    {
+      "id": "06-relationships-and-memory",
+      "title": "Relationships & Memory",
+      "summary": "Exact Memory ingest and relationship engine links — never associated* payloads on records.",
+      "path": "books/06-relationships-and-memory/"
+    },
+    {
+      "id": "07-services",
+      "title": "Building Services",
+      "summary": "When to build a service, handlers, pipeline invoke, and core-service / ports-manager / api-live-view.",
+      "path": "books/07-services/"
+    },
+    {
+      "id": "08-pipelines",
+      "title": "Building Pipelines",
+      "summary": "Pipeline definition, step kinds, AI fail-closed, operations, and the complete ops tutorial.",
+      "path": "books/08-pipelines/"
+    },
+    {
+      "id": "09-workflow-and-studio",
+      "title": "Workflow & Studio",
+      "summary": "Design · Operate · Explore — scope bar ≡ headers, workflow siblings, embedding guidance. Builders primary.",
+      "path": "books/09-workflow-and-studio/"
+    },
+    {
+      "id": "10-intelligence",
+      "title": "Structural Intelligence",
+      "summary": "Profile data, proposals with evidence, human install boundary.",
+      "path": "books/10-intelligence/"
+    },
+    {
+      "id": "11-agent-packs-and-ops",
+      "title": "Agent Packs & Ops",
+      "summary": "Pack layout, harness, g12ops* acceptance, custom kinds, golden V2 validation.",
+      "path": "books/11-agent-packs-and-ops/"
+    },
+    {
+      "id": "12-knowx",
+      "title": "Building KnowX",
+      "summary": "KnowX nodes/edges as content types, review siblings, runnable fixture path (no live AI required).",
+      "path": "books/12-knowx/"
+    },
+    {
+      "id": "13-migration-troubleshooting",
+      "title": "Migration & Troubleshooting",
+      "summary": "associated* rejection, stale revisions, HTTP failure matrix, escalate packets.",
+      "path": "books/13-migration-troubleshooting/"
+    },
+    {
+      "id": "14-getting-started-and-tutorials",
+      "title": "Getting Started & Tutorials",
+      "summary": "Start here — install @x12i/memorix-docs for agents, set scope, best-practice pipeline order, and hands-on tutorials.",
+      "path": "books/14-getting-started-and-tutorials/"
+    }
+  ]
+}

package/files/indexes/books.md

@@ -0,0 +1,17 @@
+# books
+
+- `00-platform-overview` — Platform Overview — Surfaces, packages, hard rules, and where to start — developers and builders twins.
+- `01-format-for-dummies` — Format for Dummies — Mental model of the record envelope — OT/CT, composition, discriminators, and what is not stored on the record.
+- `02-runtime-data-client` — Runtime Data Client — Connection, scope, exact reads, writes, compose, abstracts, and client anti-patterns through Memorix Service / OpenAPI.
+- `03-lists-queries-pagination` — Lists, Queries, Pagination — List contracts, query grammar, cursors, page size, and multi-resource listing without foot-guns.
+- `04-data-access-patterns` — Data Access Patterns — Decision matrix — best / acceptable / forbidden access methods for real client tasks.
+- `05-metadata-agents-abstracts` — Metadata, Agents, Abstracts & Mappings — Agents, OT/CT, virtual abstracts, mappings, install/publish — never auto-install from intelligence.
+- `06-relationships-and-memory` — Relationships & Memory — Exact Memory ingest and relationship engine links — never associated* payloads on records.
+- `07-services` — Building Services — When to build a service, handlers, pipeline invoke, and core-service / ports-manager / api-live-view.
+- `08-pipelines` — Building Pipelines — Pipeline definition, step kinds, AI fail-closed, operations, and the complete ops tutorial.
+- `09-workflow-and-studio` — Workflow & Studio — Design · Operate · Explore — scope bar ≡ headers, workflow siblings, embedding guidance. Builders primary.
+- `10-intelligence` — Structural Intelligence — Profile data, proposals with evidence, human install boundary.
+- `11-agent-packs-and-ops` — Agent Packs & Ops — Pack layout, harness, g12ops* acceptance, custom kinds, golden V2 validation.
+- `12-knowx` — Building KnowX — KnowX nodes/edges as content types, review siblings, runnable fixture path (no live AI required).
+- `13-migration-troubleshooting` — Migration & Troubleshooting — associated* rejection, stale revisions, HTTP failure matrix, escalate packets.
+- `14-getting-started-and-tutorials` — Getting Started & Tutorials — Start here — install @x12i/memorix-docs for agents, set scope, best-practice pipeline order, and hands-on tutorials.

package/files/indexes/concepts.json

@@ -0,0 +1,119 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "org-agent-scope",
+      "title": "Organization and agent scope",
+      "summary": "Scope selects which organization and agent context reads and writes apply to.",
+      "path": "concepts/org-agent-scope.md"
+    },
+    {
+      "id": "agents-inheritance",
+      "title": "Agents and inheritance",
+      "summary": "Child agents inherit definitions; Studio shows the effective result.",
+      "path": "concepts/agents-inheritance.md"
+    },
+    {
+      "id": "sources-and-memory",
+      "title": "Sources and Memory",
+      "summary": "Sources feed Memory; Memory holds durable product records.",
+      "path": "concepts/sources-and-memory.md"
+    },
+    {
+      "id": "object-content-category",
+      "title": "Object type, content type, and data category",
+      "summary": "Identity, payload shape, and category are separate axes.",
+      "path": "concepts/object-content-category.md"
+    },
+    {
+      "id": "explicit-metadata-installation",
+      "title": "Explicit metadata validation and installation",
+      "summary": "Validation does not install; installation requires confirmation.",
+      "path": "concepts/explicit-metadata-installation.md"
+    },
+    {
+      "id": "effective-metadata",
+      "title": "Effective metadata",
+      "summary": "The resolved definitions after inheritance and installation.",
+      "path": "concepts/effective-metadata.md"
+    },
+    {
+      "id": "abstracts-bindings",
+      "title": "Abstracts and bindings",
+      "summary": "An abstract is a virtual union projected through bindings — not stored rows.",
+      "path": "concepts/abstracts-bindings.md"
+    },
+    {
+      "id": "people-union",
+      "title": "People union",
+      "summary": "People combines employees and contractors through explicit bindings.",
+      "path": "concepts/people-union.md"
+    },
+    {
+      "id": "mappings-transforms",
+      "title": "Mappings and transforms",
+      "summary": "Mappings describe how source shapes become Memory content.",
+      "path": "concepts/mappings-transforms.md"
+    },
+    {
+      "id": "raw-records",
+      "title": "Raw records",
+      "summary": "Raw retains the original payload beside envelope metadata.",
+      "path": "concepts/raw-records.md"
+    },
+    {
+      "id": "composition",
+      "title": "Same-subject composition",
+      "summary": "Multiple content instances can belong to one subject when composition is explicit.",
+      "path": "concepts/composition.md"
+    },
+    {
+      "id": "relationship-definitions",
+      "title": "Relationship definitions",
+      "summary": "A relationship definition is metadata describing allowed links — not a stored edge on a record.",
+      "path": "concepts/relationship-definitions.md"
+    },
+    {
+      "id": "relationship-references",
+      "title": "Stored relationship references",
+      "summary": "Records store relationship references that point at targets under a definition.",
+      "path": "concepts/relationship-references.md"
+    },
+    {
+      "id": "traversal",
+      "title": "Forward and inverse traversal",
+      "summary": "Traversal follows definitions forward or inverse, optionally expanding targets.",
+      "path": "concepts/traversal.md"
+    },
+    {
+      "id": "resolved-unresolved",
+      "title": "Resolved and unresolved relationships",
+      "summary": "Unresolved targets are retained and shown — not silently dropped.",
+      "path": "concepts/resolved-unresolved.md"
+    },
+    {
+      "id": "record-revisions",
+      "title": "Record revisions and stale-write conflicts",
+      "summary": "Writes carry an expected revision; stale writers cannot overwrite newer data.",
+      "path": "concepts/record-revisions.md"
+    },
+    {
+      "id": "analysis-objects",
+      "title": "Analysis objects",
+      "summary": "Analysis captures evaluated evidence distinct from operational decisions.",
+      "path": "concepts/analysis-objects.md"
+    },
+    {
+      "id": "decisions-content",
+      "title": "Decisions",
+      "summary": "Decisions record chosen actions distinct from analysis content.",
+      "path": "concepts/decisions-content.md"
+    },
+    {
+      "id": "intelligence-proposals",
+      "title": "Intelligence proposals",
+      "summary": "Intelligence may propose metadata or actions but never auto-installs them.",
+      "path": "concepts/intelligence-proposals.md"
+    }
+  ]
+}

package/files/indexes/concepts.md

@@ -0,0 +1,21 @@
+# concepts
+
+- `org-agent-scope` — Organization and agent scope — Scope selects which organization and agent context reads and writes apply to.
+- `agents-inheritance` — Agents and inheritance — Child agents inherit definitions; Studio shows the effective result.
+- `sources-and-memory` — Sources and Memory — Sources feed Memory; Memory holds durable product records.
+- `object-content-category` — Object type, content type, and data category — Identity, payload shape, and category are separate axes.
+- `explicit-metadata-installation` — Explicit metadata validation and installation — Validation does not install; installation requires confirmation.
+- `effective-metadata` — Effective metadata — The resolved definitions after inheritance and installation.
+- `abstracts-bindings` — Abstracts and bindings — An abstract is a virtual union projected through bindings — not stored rows.
+- `people-union` — People union — People combines employees and contractors through explicit bindings.
+- `mappings-transforms` — Mappings and transforms — Mappings describe how source shapes become Memory content.
+- `raw-records` — Raw records — Raw retains the original payload beside envelope metadata.
+- `composition` — Same-subject composition — Multiple content instances can belong to one subject when composition is explicit.
+- `relationship-definitions` — Relationship definitions — A relationship definition is metadata describing allowed links — not a stored edge on a record.
+- `relationship-references` — Stored relationship references — Records store relationship references that point at targets under a definition.
+- `traversal` — Forward and inverse traversal — Traversal follows definitions forward or inverse, optionally expanding targets.
+- `resolved-unresolved` — Resolved and unresolved relationships — Unresolved targets are retained and shown — not silently dropped.
+- `record-revisions` — Record revisions and stale-write conflicts — Writes carry an expected revision; stale writers cannot overwrite newer data.
+- `analysis-objects` — Analysis objects — Analysis captures evaluated evidence distinct from operational decisions.
+- `decisions-content` — Decisions — Decisions record chosen actions distinct from analysis content.
+- `intelligence-proposals` — Intelligence proposals — Intelligence may propose metadata or actions but never auto-installs them.

package/files/indexes/diagrams.json

@@ -0,0 +1,53 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "memorix-central-journey",
+      "title": "Memorix central product journey",
+      "summary": "Conceptual path from scope through metadata, records, relationships, analysis, and decisions.",
+      "path": "diagrams/memorix-central-journey.md"
+    },
+    {
+      "id": "agent-inheritance",
+      "title": "Agent inheritance",
+      "summary": "Parent and child agents resolve into effective definitions.",
+      "path": "diagrams/agent-inheritance.md"
+    },
+    {
+      "id": "metadata-lifecycle",
+      "title": "Metadata lifecycle",
+      "summary": "Pack → validate → explicit install → effective resolution → runtime; proposals stay off the auto path.",
+      "path": "diagrams/metadata-lifecycle.md"
+    },
+    {
+      "id": "record-content-model",
+      "title": "Record and content model",
+      "summary": "Record identity relates to object type, content type, category, raw, snapshots, and composition.",
+      "path": "diagrams/record-content-model.md"
+    },
+    {
+      "id": "people-union-diagram",
+      "title": "People abstract union",
+      "summary": "Employees and contractors bind into the People abstract projection.",
+      "path": "diagrams/people-union-diagram.md"
+    },
+    {
+      "id": "relationship-traversal",
+      "title": "Relationship definition to traversal",
+      "summary": "Definition versus stored reference; forward/inverse; resolved versus unresolved.",
+      "path": "diagrams/relationship-traversal.md"
+    },
+    {
+      "id": "revision-safe-write",
+      "title": "Revision-safe write flow",
+      "summary": "Load, write with expected revision, success or conflict with reload/retry.",
+      "path": "diagrams/revision-safe-write.md"
+    },
+    {
+      "id": "intelligence-journey",
+      "title": "Intelligence journey",
+      "summary": "Evidence can yield analysis, decision, and proposals that still require explicit install.",
+      "path": "diagrams/intelligence-journey.md"
+    }
+  ]
+}

package/files/indexes/diagrams.md

@@ -0,0 +1,10 @@
+# diagrams
+
+- `memorix-central-journey` — Memorix central product journey — Conceptual path from scope through metadata, records, relationships, analysis, and decisions.
+- `agent-inheritance` — Agent inheritance — Parent and child agents resolve into effective definitions.
+- `metadata-lifecycle` — Metadata lifecycle — Pack → validate → explicit install → effective resolution → runtime; proposals stay off the auto path.
+- `record-content-model` — Record and content model — Record identity relates to object type, content type, category, raw, snapshots, and composition.
+- `people-union-diagram` — People abstract union — Employees and contractors bind into the People abstract projection.
+- `relationship-traversal` — Relationship definition to traversal — Definition versus stored reference; forward/inverse; resolved versus unresolved.
+- `revision-safe-write` — Revision-safe write flow — Load, write with expected revision, success or conflict with reload/retry.
+- `intelligence-journey` — Intelligence journey — Evidence can yield analysis, decision, and proposals that still require explicit install.

package/files/indexes/guides.json

@@ -0,0 +1,71 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "apply-scope",
+      "title": "Select and apply organization/agent scope",
+      "summary": "Set the workspace scope before reading or writing.",
+      "path": "guides/apply-scope.md"
+    },
+    {
+      "id": "inspect-effective-metadata",
+      "title": "Inspect effective metadata before read/write",
+      "summary": "Confirm effective definitions before mutating records.",
+      "path": "guides/inspect-effective-metadata.md"
+    },
+    {
+      "id": "choose-access-method",
+      "title": "Choose raw, composed, or abstract access",
+      "summary": "Pick the fidelity that matches the caller goal.",
+      "path": "guides/choose-access-method.md"
+    },
+    {
+      "id": "first-revision-safe-write",
+      "title": "Perform a first revision-safe read/write",
+      "summary": "Read a record, write with expected revision, verify.",
+      "path": "guides/first-revision-safe-write.md"
+    },
+    {
+      "id": "reload-retry-conflict",
+      "title": "Reload, compare, and retry after a revision conflict",
+      "summary": "Recover safely when a stale write is rejected.",
+      "path": "guides/reload-retry-conflict.md"
+    },
+    {
+      "id": "validate-install-pack",
+      "title": "Validate and explicitly install a metadata pack",
+      "summary": "Validate first, then confirm installation.",
+      "path": "guides/validate-install-pack.md"
+    },
+    {
+      "id": "define-traverse-relationship",
+      "title": "Define and traverse a relationship",
+      "summary": "Author a definition, store a reference, traverse forward/inverse.",
+      "path": "guides/define-traverse-relationship.md"
+    },
+    {
+      "id": "diagnose-unresolved",
+      "title": "Diagnose an unresolved relationship target",
+      "summary": "Distinguish intentional unresolved from broken targets.",
+      "path": "guides/diagnose-unresolved.md"
+    },
+    {
+      "id": "compose-subject-ui",
+      "title": "Compose same-subject content for a UI",
+      "summary": "Load composition for a subject the UI will render.",
+      "path": "guides/compose-subject-ui.md"
+    },
+    {
+      "id": "query-people-abstract",
+      "title": "Query the People abstract view",
+      "summary": "Read employees and contractors through People bindings.",
+      "path": "guides/query-people-abstract.md"
+    },
+    {
+      "id": "evidence-to-decision",
+      "title": "Move from evidence to analysis and a decision",
+      "summary": "Record analysis, then a distinct decision.",
+      "path": "guides/evidence-to-decision.md"
+    }
+  ]
+}

package/files/indexes/guides.md

@@ -0,0 +1,13 @@
+# guides
+
+- `apply-scope` — Select and apply organization/agent scope — Set the workspace scope before reading or writing.
+- `inspect-effective-metadata` — Inspect effective metadata before read/write — Confirm effective definitions before mutating records.
+- `choose-access-method` — Choose raw, composed, or abstract access — Pick the fidelity that matches the caller goal.
+- `first-revision-safe-write` — Perform a first revision-safe read/write — Read a record, write with expected revision, verify.
+- `reload-retry-conflict` — Reload, compare, and retry after a revision conflict — Recover safely when a stale write is rejected.
+- `validate-install-pack` — Validate and explicitly install a metadata pack — Validate first, then confirm installation.
+- `define-traverse-relationship` — Define and traverse a relationship — Author a definition, store a reference, traverse forward/inverse.
+- `diagnose-unresolved` — Diagnose an unresolved relationship target — Distinguish intentional unresolved from broken targets.
+- `compose-subject-ui` — Compose same-subject content for a UI — Load composition for a subject the UI will render.
+- `query-people-abstract` — Query the People abstract view — Read employees and contractors through People bindings.
+- `evidence-to-decision` — Move from evidence to analysis and a decision — Record analysis, then a distinct decision.

package/files/indexes/scenarios.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "scope-mismatch",
+      "title": "Scope does not match the intended workspace",
+      "summary": "Detected organization/agent scope differs from the task.",
+      "path": "scenarios/scope-mismatch.md"
+    },
+    {
+      "id": "stale-revision-conflict",
+      "title": "A write returns a stale-revision conflict",
+      "summary": "PATCH/PUT rejected because expected revision was stale.",
+      "path": "scenarios/stale-revision-conflict.md"
+    },
+    {
+      "id": "unresolved-relationship",
+      "title": "A relationship target is unresolved",
+      "summary": "Traversal returns an unresolved target marker.",
+      "path": "scenarios/unresolved-relationship.md"
+    },
+    {
+      "id": "pack-valid-not-installed",
+      "title": "A metadata pack is valid but not installed",
+      "summary": "Validation succeeded; runtime still on previous effective metadata.",
+      "path": "scenarios/pack-valid-not-installed.md"
+    },
+    {
+      "id": "choose-subject-view",
+      "title": "A caller needs a subject view",
+      "summary": "Choose raw, composition, or abstract based on fidelity needs.",
+      "path": "scenarios/choose-subject-view.md"
+    },
+    {
+      "id": "traversal-direction",
+      "title": "Relationship traversal direction and expansion",
+      "summary": "Choose forward/inverse and expanded/unexpanded handling.",
+      "path": "scenarios/traversal-direction.md"
+    }
+  ]
+}

package/files/indexes/scenarios.md

@@ -0,0 +1,8 @@
+# scenarios
+
+- `scope-mismatch` — Scope does not match the intended workspace — Detected organization/agent scope differs from the task.
+- `stale-revision-conflict` — A write returns a stale-revision conflict — PATCH/PUT rejected because expected revision was stale.
+- `unresolved-relationship` — A relationship target is unresolved — Traversal returns an unresolved target marker.
+- `pack-valid-not-installed` — A metadata pack is valid but not installed — Validation succeeded; runtime still on previous effective metadata.
+- `choose-subject-view` — A caller needs a subject view — Choose raw, composition, or abstract based on fidelity needs.
+- `traversal-direction` — Relationship traversal direction and expansion — Choose forward/inverse and expanded/unexpanded handling.