@x12i/memorix-docs 1.0.2 → 1.1.1

package/files/INDEX.md

@@ -0,0 +1,84 @@
+# memorix — knowledge index
+
+Package: `@x12i/memorix-docs`
+
+## How to choose
+
+- **Concept** — what it is and why it exists
+- **Guide** — bounded task procedure
+- **Scenario** — state + evidence → which path
+- **Use case** — end-to-end outcome
+- **Tutorial** — learn by doing
+- **Decision** — options and recommended default
+- **Reference / API** — exact technical detail
+
+## Manifest and search
+
+- `agent-manifest.json`
+- `SEARCH.json`
+
+## Concepts
+
+- `org-agent-scope` — **Organization and agent scope** — Scope selects which organization and agent context reads and writes apply to. — [concepts/org-agent-scope.md](concepts/org-agent-scope.md)
+- `agents-inheritance` — **Agents and inheritance** — Child agents inherit definitions; Studio shows the effective result. — [concepts/agents-inheritance.md](concepts/agents-inheritance.md)
+- `sources-and-memory` — **Sources and Memory** — Sources feed Memory; Memory holds durable product records. — [concepts/sources-and-memory.md](concepts/sources-and-memory.md)
+- `object-content-category` — **Object type, content type, and data category** — Identity, payload shape, and category are separate axes. — [concepts/object-content-category.md](concepts/object-content-category.md)
+- `explicit-metadata-installation` — **Explicit metadata validation and installation** — Validation does not install; installation requires confirmation. — [concepts/explicit-metadata-installation.md](concepts/explicit-metadata-installation.md)
+- `effective-metadata` — **Effective metadata** — The resolved definitions after inheritance and installation. — [concepts/effective-metadata.md](concepts/effective-metadata.md)
+- `abstracts-bindings` — **Abstracts and bindings** — An abstract is a virtual union projected through bindings — not stored rows. — [concepts/abstracts-bindings.md](concepts/abstracts-bindings.md)
+- `people-union` — **People union** — People combines employees and contractors through explicit bindings. — [concepts/people-union.md](concepts/people-union.md)
+- `mappings-transforms` — **Mappings and transforms** — Mappings describe how source shapes become Memory content. — [concepts/mappings-transforms.md](concepts/mappings-transforms.md)
+- `raw-records` — **Raw records** — Raw retains the original payload beside envelope metadata. — [concepts/raw-records.md](concepts/raw-records.md)
+- `composition` — **Same-subject composition** — Multiple content instances can belong to one subject when composition is explicit. — [concepts/composition.md](concepts/composition.md)
+- `relationship-definitions` — **Relationship definitions** — A relationship definition is metadata describing allowed links — not a stored edge on a record. — [concepts/relationship-definitions.md](concepts/relationship-definitions.md)
+- `relationship-references` — **Stored relationship references** — Records store relationship references that point at targets under a definition. — [concepts/relationship-references.md](concepts/relationship-references.md)
+- `traversal` — **Forward and inverse traversal** — Traversal follows definitions forward or inverse, optionally expanding targets. — [concepts/traversal.md](concepts/traversal.md)
+- `resolved-unresolved` — **Resolved and unresolved relationships** — Unresolved targets are retained and shown — not silently dropped. — [concepts/resolved-unresolved.md](concepts/resolved-unresolved.md)
+- `record-revisions` — **Record revisions and stale-write conflicts** — Writes carry an expected revision; stale writers cannot overwrite newer data. — [concepts/record-revisions.md](concepts/record-revisions.md)
+- `analysis-objects` — **Analysis objects** — Analysis captures evaluated evidence distinct from operational decisions. — [concepts/analysis-objects.md](concepts/analysis-objects.md)
+- `decisions-content` — **Decisions** — Decisions record chosen actions distinct from analysis content. — [concepts/decisions-content.md](concepts/decisions-content.md)
+- `intelligence-proposals` — **Intelligence proposals** — Intelligence may propose metadata or actions but never auto-installs them. — [concepts/intelligence-proposals.md](concepts/intelligence-proposals.md)
+
+## Guides
+
+- `apply-scope` — **Select and apply organization/agent scope** — Set the workspace scope before reading or writing. — [guides/apply-scope.md](guides/apply-scope.md)
+- `inspect-effective-metadata` — **Inspect effective metadata before read/write** — Confirm effective definitions before mutating records. — [guides/inspect-effective-metadata.md](guides/inspect-effective-metadata.md)
+- `choose-access-method` — **Choose raw, composed, or abstract access** — Pick the fidelity that matches the caller goal. — [guides/choose-access-method.md](guides/choose-access-method.md)
+- `first-revision-safe-write` — **Perform a first revision-safe read/write** — Read a record, write with expected revision, verify. — [guides/first-revision-safe-write.md](guides/first-revision-safe-write.md)
+- `reload-retry-conflict` — **Reload, compare, and retry after a revision conflict** — Recover safely when a stale write is rejected. — [guides/reload-retry-conflict.md](guides/reload-retry-conflict.md)
+- `validate-install-pack` — **Validate and explicitly install a metadata pack** — Validate first, then confirm installation. — [guides/validate-install-pack.md](guides/validate-install-pack.md)
+- `define-traverse-relationship` — **Define and traverse a relationship** — Author a definition, store a reference, traverse forward/inverse. — [guides/define-traverse-relationship.md](guides/define-traverse-relationship.md)
+- `diagnose-unresolved` — **Diagnose an unresolved relationship target** — Distinguish intentional unresolved from broken targets. — [guides/diagnose-unresolved.md](guides/diagnose-unresolved.md)
+- `compose-subject-ui` — **Compose same-subject content for a UI** — Load composition for a subject the UI will render. — [guides/compose-subject-ui.md](guides/compose-subject-ui.md)
+- `query-people-abstract` — **Query the People abstract view** — Read employees and contractors through People bindings. — [guides/query-people-abstract.md](guides/query-people-abstract.md)
+- `evidence-to-decision` — **Move from evidence to analysis and a decision** — Record analysis, then a distinct decision. — [guides/evidence-to-decision.md](guides/evidence-to-decision.md)
+
+## Scenarios
+
+- `scope-mismatch` — **Scope does not match the intended workspace** — Detected organization/agent scope differs from the task. — [scenarios/scope-mismatch.md](scenarios/scope-mismatch.md)
+- `stale-revision-conflict` — **A write returns a stale-revision conflict** — PATCH/PUT rejected because expected revision was stale. — [scenarios/stale-revision-conflict.md](scenarios/stale-revision-conflict.md)
+- `unresolved-relationship` — **A relationship target is unresolved** — Traversal returns an unresolved target marker. — [scenarios/unresolved-relationship.md](scenarios/unresolved-relationship.md)
+- `pack-valid-not-installed` — **A metadata pack is valid but not installed** — Validation succeeded; runtime still on previous effective metadata. — [scenarios/pack-valid-not-installed.md](scenarios/pack-valid-not-installed.md)
+- `choose-subject-view` — **A caller needs a subject view** — Choose raw, composition, or abstract based on fidelity needs. — [scenarios/choose-subject-view.md](scenarios/choose-subject-view.md)
+- `traversal-direction` — **Relationship traversal direction and expansion** — Choose forward/inverse and expanded/unexpanded handling. — [scenarios/traversal-direction.md](scenarios/traversal-direction.md)
+
+## Diagrams
+
+- `memorix-central-journey` — **Memorix central product journey** — Conceptual path from scope through metadata, records, relationships, analysis, and decisions. — [diagrams/memorix-central-journey.md](diagrams/memorix-central-journey.md)
+- `agent-inheritance` — **Agent inheritance** — Parent and child agents resolve into effective definitions. — [diagrams/agent-inheritance.md](diagrams/agent-inheritance.md)
+- `metadata-lifecycle` — **Metadata lifecycle** — Pack → validate → explicit install → effective resolution → runtime; proposals stay off the auto path. — [diagrams/metadata-lifecycle.md](diagrams/metadata-lifecycle.md)
+- `record-content-model` — **Record and content model** — Record identity relates to object type, content type, category, raw, snapshots, and composition. — [diagrams/record-content-model.md](diagrams/record-content-model.md)
+- `people-union-diagram` — **People abstract union** — Employees and contractors bind into the People abstract projection. — [diagrams/people-union-diagram.md](diagrams/people-union-diagram.md)
+- `relationship-traversal` — **Relationship definition to traversal** — Definition versus stored reference; forward/inverse; resolved versus unresolved. — [diagrams/relationship-traversal.md](diagrams/relationship-traversal.md)
+- `revision-safe-write` — **Revision-safe write flow** — Load, write with expected revision, success or conflict with reload/retry. — [diagrams/revision-safe-write.md](diagrams/revision-safe-write.md)
+- `intelligence-journey` — **Intelligence journey** — Evidence can yield analysis, decision, and proposals that still require explicit install. — [diagrams/intelligence-journey.md](diagrams/intelligence-journey.md)
+
+## Tutorials
+
+- `start-with-sample-data` — **Start Memorix with the sample dataset** — Load the synthetic dataset and confirm scope. — [tutorials/start-with-sample-data.md](tutorials/start-with-sample-data.md)
+- `first-revision-safe-record` — **Read and write the first revision-safe record** — Practice expected-revision writes on sample data. — [tutorials/first-revision-safe-record.md](tutorials/first-revision-safe-record.md)
+- `compare-views` — **Compare raw, composed, and abstract views** — See fidelity differences on the same subjects. — [tutorials/compare-views.md](tutorials/compare-views.md)
+- `relationships-lab` — **Define, store, and traverse relationships** — Hands-on relationship definition and traversal. — [tutorials/relationships-lab.md](tutorials/relationships-lab.md)
+- `conflict-lab` — **Recover from a stale revision conflict** — Trigger and recover from a conflict using sample data. — [tutorials/conflict-lab.md](tutorials/conflict-lab.md)
+- `install-pack-lab` — **Validate and explicitly install a metadata pack** — Practice validation versus confirmation. — [tutorials/install-pack-lab.md](tutorials/install-pack-lab.md)
+- `analysis-decision-lab` — **Move from records to analysis and a decision** — Create analysis then a distinct decision on sample evidence. — [tutorials/analysis-decision-lab.md](tutorials/analysis-decision-lab.md)