@x12i/memorix-docs 1.0.2 → 1.1.1

package/files/indexes/tutorials.json

@@ -0,0 +1,47 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "start-with-sample-data",
+      "title": "Start Memorix with the sample dataset",
+      "summary": "Load the synthetic dataset and confirm scope.",
+      "path": "tutorials/start-with-sample-data.md"
+    },
+    {
+      "id": "first-revision-safe-record",
+      "title": "Read and write the first revision-safe record",
+      "summary": "Practice expected-revision writes on sample data.",
+      "path": "tutorials/first-revision-safe-record.md"
+    },
+    {
+      "id": "compare-views",
+      "title": "Compare raw, composed, and abstract views",
+      "summary": "See fidelity differences on the same subjects.",
+      "path": "tutorials/compare-views.md"
+    },
+    {
+      "id": "relationships-lab",
+      "title": "Define, store, and traverse relationships",
+      "summary": "Hands-on relationship definition and traversal.",
+      "path": "tutorials/relationships-lab.md"
+    },
+    {
+      "id": "conflict-lab",
+      "title": "Recover from a stale revision conflict",
+      "summary": "Trigger and recover from a conflict using sample data.",
+      "path": "tutorials/conflict-lab.md"
+    },
+    {
+      "id": "install-pack-lab",
+      "title": "Validate and explicitly install a metadata pack",
+      "summary": "Practice validation versus confirmation.",
+      "path": "tutorials/install-pack-lab.md"
+    },
+    {
+      "id": "analysis-decision-lab",
+      "title": "Move from records to analysis and a decision",
+      "summary": "Create analysis then a distinct decision on sample evidence.",
+      "path": "tutorials/analysis-decision-lab.md"
+    }
+  ]
+}

package/files/indexes/tutorials.md

@@ -0,0 +1,9 @@
+# tutorials
+
+- `start-with-sample-data` — Start Memorix with the sample dataset — Load the synthetic dataset and confirm scope.
+- `first-revision-safe-record` — Read and write the first revision-safe record — Practice expected-revision writes on sample data.
+- `compare-views` — Compare raw, composed, and abstract views — See fidelity differences on the same subjects.
+- `relationships-lab` — Define, store, and traverse relationships — Hands-on relationship definition and traversal.
+- `conflict-lab` — Recover from a stale revision conflict — Trigger and recover from a conflict using sample data.
+- `install-pack-lab` — Validate and explicitly install a metadata pack — Practice validation versus confirmation.
+- `analysis-decision-lab` — Move from records to analysis and a decision — Create analysis then a distinct decision on sample evidence.

package/files/indexes/use-cases.json

@@ -0,0 +1,239 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "start-from-zero",
+      "title": "Start Memorix from zero",
+      "summary": "Install docs for your agents, set scope, run the stack, and walk the tutorials to the core loop.",
+      "path": "use-cases/start-from-zero.md"
+    },
+    {
+      "id": "orient-platform",
+      "title": "Orient on Memorix after G12",
+      "summary": "Understand surfaces, packages, hard rules, and which ebook to open next.",
+      "path": "use-cases/orient-platform.md"
+    },
+    {
+      "id": "learn-record-envelope",
+      "title": "Learn the memorix-record/2 envelope",
+      "summary": "Internalize OT/CT, composition, discriminators, and what must not live on the record.",
+      "path": "use-cases/learn-record-envelope.md"
+    },
+    {
+      "id": "client-first-read-write",
+      "title": "Product backend first safe read/write",
+      "summary": "Call /api/data correctly with scope, revision preconditions, and explicit compose.",
+      "path": "use-cases/client-first-read-write.md"
+    },
+    {
+      "id": "choose-access-method",
+      "title": "Choose the right access method",
+      "summary": "Map a task to best / acceptable / forbidden calls using the patterns matrix.",
+      "path": "use-cases/choose-access-method.md"
+    },
+    {
+      "id": "lists-cursors-pagination",
+      "title": "List, filter, and paginate correctly",
+      "summary": "Use cursors, pageInfo, and query grammar without inventing offsets.",
+      "path": "use-cases/lists-cursors-pagination.md"
+    },
+    {
+      "id": "compose-for-ui",
+      "title": "Compose a subject for a UI view",
+      "summary": "Use explicit composition instead of N+1 gets for a subject screen.",
+      "path": "use-cases/compose-for-ui.md"
+    },
+    {
+      "id": "abstract-people-list",
+      "title": "Multi-type abstract list (People)",
+      "summary": "List across concrete types via abstracts and reverse-map writes.",
+      "path": "use-cases/abstract-people-list.md"
+    },
+    {
+      "id": "metadata-before-write",
+      "title": "Discover effective metadata before writing",
+      "summary": "Load views/writes from /api/metadata so clients do not invent shapes.",
+      "path": "use-cases/metadata-before-write.md"
+    },
+    {
+      "id": "revision-stale-conflicts",
+      "title": "Handle revision / stale conflicts",
+      "summary": "Patch with revision preconditions and recover when another writer won.",
+      "path": "use-cases/revision-stale-conflicts.md"
+    },
+    {
+      "id": "discriminated-content-writes",
+      "title": "Write analysis / decision / narrative content",
+      "summary": "Use discriminators correctly for sibling content types.",
+      "path": "use-cases/discriminated-content-writes.md"
+    },
+    {
+      "id": "memory-hourly-ingest",
+      "title": "Ingest an external system on a schedule",
+      "summary": "Land exact provider payloads in Memory, then map/write via pipeline.",
+      "path": "use-cases/memory-hourly-ingest.md"
+    },
+    {
+      "id": "four-field-links",
+      "title": "Link subjects with four-field relationships",
+      "summary": "Define relationships, expand on read, never store associated* on records.",
+      "path": "use-cases/four-field-links.md"
+    },
+    {
+      "id": "relationship-rebuild-verify",
+      "title": "Rebuild and verify relationship links",
+      "summary": "Run discover / verify / rebuild / cleanup through the relationship engine.",
+      "path": "use-cases/relationship-rebuild-verify.md"
+    },
+    {
+      "id": "install-metadata-pack",
+      "title": "Author and install a metadata pack",
+      "summary": "Shape agents/OT/CT/abstracts and install/publish deliberately — never auto.",
+      "path": "use-cases/install-metadata-pack.md"
+    },
+    {
+      "id": "custom-kind-descriptors",
+      "title": "Store custom UI kind descriptors",
+      "summary": "Use kindDeclarations / extensions for client-owned tabs without a new engine.",
+      "path": "use-cases/custom-kind-descriptors.md"
+    },
+    {
+      "id": "build-callable-service",
+      "title": "Build a service Memorix pipelines invoke",
+      "summary": "Decide you need a service, define it, implement handlers, bind, and invoke from a step.",
+      "path": "use-cases/build-callable-service.md"
+    },
+    {
+      "id": "http-process-compliance",
+      "title": "HTTP process compliance (ports / health / live)",
+      "summary": "Wire core-service, ports-manager, and api-live-view for any process that binds HTTP.",
+      "path": "use-cases/http-process-compliance.md"
+    },
+    {
+      "id": "author-pipeline-e2e",
+      "title": "Author and run a pipeline end-to-end",
+      "summary": "Define steps, execute under g12ops*, and observe runs/artifacts.",
+      "path": "use-cases/author-pipeline-e2e.md"
+    },
+    {
+      "id": "ai-pipeline-fail-closed",
+      "title": "AI pipeline steps fail closed",
+      "summary": "Add AI steps without silent invention; keep validation and retries honest.",
+      "path": "use-cases/ai-pipeline-fail-closed.md"
+    },
+    {
+      "id": "pipeline-retry-evidence",
+      "title": "Retry a failed pipeline step with evidence",
+      "summary": "Operate failed attempts, retry safely, and keep artifacts for forensics.",
+      "path": "use-cases/pipeline-retry-evidence.md"
+    },
+    {
+      "id": "embed-studio-host",
+      "title": "Embed Studio in a host app",
+      "summary": "Map scope bar to HTTP headers and embed the sole product UI correctly.",
+      "path": "use-cases/embed-studio-host.md"
+    },
+    {
+      "id": "workflow-sibling-api",
+      "title": "Work with workflow sibling content via API",
+      "summary": "Treat workflow as sibling content under /api/workflow, not a separate product.",
+      "path": "use-cases/workflow-sibling-api.md"
+    },
+    {
+      "id": "intelligence-propose-install",
+      "title": "Intelligence propose → human install",
+      "summary": "Profile and propose metadata, then install only via deliberate human action.",
+      "path": "use-cases/intelligence-propose-install.md"
+    },
+    {
+      "id": "ops-pack-fixtures",
+      "title": "Package ops fixtures and acceptance harness",
+      "summary": "Build or extend an agent pack with g12ops* acceptance, goldens, and harness commands.",
+      "path": "use-cases/ops-pack-fixtures.md"
+    },
+    {
+      "id": "knowx-claims-review",
+      "title": "Build KnowX claims with human review",
+      "summary": "Model NODE/EDGE claims with provenance and run the fixture path without live AI.",
+      "path": "use-cases/knowx-claims-review.md"
+    },
+    {
+      "id": "migrate-associated-star",
+      "title": "Migrate associated* present format to V2",
+      "summary": "Reject associated* payloads and migrate envelopes with memorix-format tooling.",
+      "path": "use-cases/migrate-associated-star.md"
+    },
+    {
+      "id": "troubleshoot-http-matrix",
+      "title": "Troubleshoot runtime HTTP failures",
+      "summary": "Use the failure matrix and escalate packet when stuck.",
+      "path": "use-cases/troubleshoot-http-matrix.md"
+    },
+    {
+      "id": "trusted-in-process-embed",
+      "title": "Embed Memorix engines in a trusted host",
+      "summary": "Know when in-process packages are allowed vs remote HTTP-only clients.",
+      "path": "use-cases/trusted-in-process-embed.md"
+    },
+    {
+      "id": "data-journey-evidence",
+      "title": "Use data-journey matrix and evidence APIs",
+      "summary": "Drive Explore/evidence UIs via /api/data-journey without inventing coverage rules.",
+      "path": "use-cases/data-journey-evidence.md"
+    },
+    {
+      "id": "local-acceptance-g12ops",
+      "title": "Run local acceptance on g12ops*",
+      "summary": "Bring up the stack with ops-pack and prove the ops narrative in an isolated org.",
+      "path": "use-cases/local-acceptance-g12ops.md"
+    },
+    {
+      "id": "openapi-typed-client",
+      "title": "Orient on OpenAPI / typed clients",
+      "summary": "Find OpenAPI generation workflow and keep clients aligned with the service.",
+      "path": "use-cases/openapi-typed-client.md"
+    },
+    {
+      "id": "studio-design-types",
+      "title": "Design object and content types in Studio",
+      "summary": "Change product shape in Design without shipping engine code.",
+      "path": "use-cases/studio-design-types.md"
+    },
+    {
+      "id": "studio-operate-pipelines",
+      "title": "Operate pipelines in Studio",
+      "summary": "Run, retry, and inspect pipeline health from Operate.",
+      "path": "use-cases/studio-operate-pipelines.md"
+    },
+    {
+      "id": "studio-explore-subject",
+      "title": "Explore a composed subject in Studio",
+      "summary": "Read composition vs relationships visually in Explore.",
+      "path": "use-cases/studio-explore-subject.md"
+    },
+    {
+      "id": "studio-review-intelligence",
+      "title": "Review intelligence proposals in Studio",
+      "summary": "Accept evidence, reject bad proposals, install only deliberately.",
+      "path": "use-cases/studio-review-intelligence.md"
+    },
+    {
+      "id": "studio-stale-conflict-ui",
+      "title": "Resolve stale conflicts from the UI",
+      "summary": "Recognize revision conflicts and recover without losing the other writer’s work blindly.",
+      "path": "use-cases/studio-stale-conflict-ui.md"
+    },
+    {
+      "id": "studio-scope-isolation",
+      "title": "Keep workspaces isolated via the scope bar",
+      "summary": "Never mix orgs/workspaces; treat scope as the product boundary.",
+      "path": "use-cases/studio-scope-isolation.md"
+    },
+    {
+      "id": "builder-acceptance-ops",
+      "title": "Acceptance tour on the ops narrative",
+      "summary": "Walk WI-100 / employees success path in Studio without API deep-dive.",
+      "path": "use-cases/builder-acceptance-ops.md"
+    }
+  ]
+}

package/files/indexes/use-cases.md

@@ -0,0 +1,41 @@
+# use-cases
+
+- `start-from-zero` — Start Memorix from zero — Install docs for your agents, set scope, run the stack, and walk the tutorials to the core loop.
+- `orient-platform` — Orient on Memorix after G12 — Understand surfaces, packages, hard rules, and which ebook to open next.
+- `learn-record-envelope` — Learn the memorix-record/2 envelope — Internalize OT/CT, composition, discriminators, and what must not live on the record.
+- `client-first-read-write` — Product backend first safe read/write — Call /api/data correctly with scope, revision preconditions, and explicit compose.
+- `choose-access-method` — Choose the right access method — Map a task to best / acceptable / forbidden calls using the patterns matrix.
+- `lists-cursors-pagination` — List, filter, and paginate correctly — Use cursors, pageInfo, and query grammar without inventing offsets.
+- `compose-for-ui` — Compose a subject for a UI view — Use explicit composition instead of N+1 gets for a subject screen.
+- `abstract-people-list` — Multi-type abstract list (People) — List across concrete types via abstracts and reverse-map writes.
+- `metadata-before-write` — Discover effective metadata before writing — Load views/writes from /api/metadata so clients do not invent shapes.
+- `revision-stale-conflicts` — Handle revision / stale conflicts — Patch with revision preconditions and recover when another writer won.
+- `discriminated-content-writes` — Write analysis / decision / narrative content — Use discriminators correctly for sibling content types.
+- `memory-hourly-ingest` — Ingest an external system on a schedule — Land exact provider payloads in Memory, then map/write via pipeline.
+- `four-field-links` — Link subjects with four-field relationships — Define relationships, expand on read, never store associated* on records.
+- `relationship-rebuild-verify` — Rebuild and verify relationship links — Run discover / verify / rebuild / cleanup through the relationship engine.
+- `install-metadata-pack` — Author and install a metadata pack — Shape agents/OT/CT/abstracts and install/publish deliberately — never auto.
+- `custom-kind-descriptors` — Store custom UI kind descriptors — Use kindDeclarations / extensions for client-owned tabs without a new engine.
+- `build-callable-service` — Build a service Memorix pipelines invoke — Decide you need a service, define it, implement handlers, bind, and invoke from a step.
+- `http-process-compliance` — HTTP process compliance (ports / health / live) — Wire core-service, ports-manager, and api-live-view for any process that binds HTTP.
+- `author-pipeline-e2e` — Author and run a pipeline end-to-end — Define steps, execute under g12ops*, and observe runs/artifacts.
+- `ai-pipeline-fail-closed` — AI pipeline steps fail closed — Add AI steps without silent invention; keep validation and retries honest.
+- `pipeline-retry-evidence` — Retry a failed pipeline step with evidence — Operate failed attempts, retry safely, and keep artifacts for forensics.
+- `embed-studio-host` — Embed Studio in a host app — Map scope bar to HTTP headers and embed the sole product UI correctly.
+- `workflow-sibling-api` — Work with workflow sibling content via API — Treat workflow as sibling content under /api/workflow, not a separate product.
+- `intelligence-propose-install` — Intelligence propose → human install — Profile and propose metadata, then install only via deliberate human action.
+- `ops-pack-fixtures` — Package ops fixtures and acceptance harness — Build or extend an agent pack with g12ops* acceptance, goldens, and harness commands.
+- `knowx-claims-review` — Build KnowX claims with human review — Model NODE/EDGE claims with provenance and run the fixture path without live AI.
+- `migrate-associated-star` — Migrate associated* present format to V2 — Reject associated* payloads and migrate envelopes with memorix-format tooling.
+- `troubleshoot-http-matrix` — Troubleshoot runtime HTTP failures — Use the failure matrix and escalate packet when stuck.
+- `trusted-in-process-embed` — Embed Memorix engines in a trusted host — Know when in-process packages are allowed vs remote HTTP-only clients.
+- `data-journey-evidence` — Use data-journey matrix and evidence APIs — Drive Explore/evidence UIs via /api/data-journey without inventing coverage rules.
+- `local-acceptance-g12ops` — Run local acceptance on g12ops* — Bring up the stack with ops-pack and prove the ops narrative in an isolated org.
+- `openapi-typed-client` — Orient on OpenAPI / typed clients — Find OpenAPI generation workflow and keep clients aligned with the service.
+- `studio-design-types` — Design object and content types in Studio — Change product shape in Design without shipping engine code.
+- `studio-operate-pipelines` — Operate pipelines in Studio — Run, retry, and inspect pipeline health from Operate.
+- `studio-explore-subject` — Explore a composed subject in Studio — Read composition vs relationships visually in Explore.
+- `studio-review-intelligence` — Review intelligence proposals in Studio — Accept evidence, reject bad proposals, install only deliberately.
+- `studio-stale-conflict-ui` — Resolve stale conflicts from the UI — Recognize revision conflicts and recover without losing the other writer’s work blindly.
+- `studio-scope-isolation` — Keep workspaces isolated via the scope bar — Never mix orgs/workspaces; treat scope as the product boundary.
+- `builder-acceptance-ops` — Acceptance tour on the ops narrative — Walk WI-100 / employees success path in Studio without API deep-dive.