@x12i/memorix-docs 1.0.1 → 1.1.0

package/files/use-cases/compose-for-ui.md

@@ -0,0 +1,97 @@
+# Compose a subject for a UI view
+
+> **Use case id:** `compose-for-ui`
+> **Goal:** Use explicit composition instead of N+1 gets for a subject screen.
+> **Audiences:** developers
+> **Tags:** compose, ui, http
+
+## Reading path
+
+1. **Runtime Data Client** (developers) → chapters: `6-explicit-composition`
+1. **Data Access Patterns** (developers) → chapters: `6-composition-versus-multiple-gets`
+
+## From: Runtime Data Client — 6. Explicit composition
+
+Composition is **requested**. Same `recordId`, multiple content types/instances.
+
+### Shape rules
+
+- Response uses **arrays per content type** (even singleton types appear as arrays in compose).
+- Siblings are **not** flattened into one mega-document.
+- Clients may select which content types to include.
+- Workflow / context / analysis / decisions appear only when selected.
+- Composition carries **no** relationship definitions — neighbors stay relationship APIs.
+
+### Ops examples
+
+| Request | Result idea |
+|---|---|
+| Compose `wi-100` with `snapshots` + `workflow` | One snapshot array entry + workflow array entry |
+| Include two analyses | `analysis: [capacity, delivery-risk]` (names illustrative) |
+| Include three decisions | Arrays under decisions; independent revisions |
+| Optional sibling missing | Empty array or omitted per contract — not a fake null record |
+
+```text
+composeSubject(wi-100)
+  snapshots[]     revision N
+  workflow[]      revision M
+  analysis[]      each own revision
+  decisions[]     each own revision
+```
+
+```bash
+curl -sS -X POST \
+  -H "content-type: application/json" \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  -d '{"recordId":"wi-100","explicit":true,"contentTypes":["snapshots","workflow","analysis","decisions"]}' \
+  "$BASE/api/data/compose"
+```
+
+OpenAPI operation: `dataCompose`. `explicit: true` is required. Response keeps **arrays per content type**; missing siblings are empty/omitted arrays (plus warnings when the contract exposes them) — not invented singleton objects.
+
+### May / must-not
+
+- **You may** compose for a dossier / Studio Explore-style view.
+- **You must not** invent a single “subject revision” by taking `max(sibling revisions)`.
+- **You must not** flatten arrays into one object keyed only by content type when multiple discriminators exist.
+- **You must not** call compose as `GET` with query params — the service accepts **`POST /api/data/compose`** only.
+
+---
+
+## From: Data Access Patterns — 6. Composition versus multiple gets
+
+**Preferred:** request explicit composition when the client needs several sibling content types for one subject (snapshot + workflow + decisions for `wi-100`).
+
+**Acceptable:** separate exact reads when only one or two independently refreshed siblings are needed (e.g. poll workflow alone).
+
+**Avoid:**
+
+- Fetching every registered sibling automatically
+- Flattening siblings into the snapshot payload
+- Treating analysis/workflow as relationships
+- Caching composition as a new authoritative stored record
+
+Composition is **virtual**. Sibling instances keep independent revisions. Payload size and freshness trade off: compose once for a dossier screen; refresh one sibling when only that pane changed.
+
+```text
+Subject wi-100
+  ├─ snapshots     (revision N)
+  ├─ workflow      (revision M)
+  ├─ decisions[]   (per-instance revisions)
+  └─ analysis[]    (per-instance revisions)
+```
+
+**Best:** compose API / `composeSubject`.  
+**Acceptable:** multiple gets of **references / envelopes**, assembled in the client without copying neighbor `.data` into the source.  
+**Forbidden:** embed copied neighbor payloads (`associated*` revival).
+
+---
+
+## Also see
+
+- **Format for Dummies** (`01-format-for-dummies`) — Mental model of the record envelope — OT/CT, composition, discriminators, and what is not stored on the record.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/custom-kind-descriptors.md

@@ -0,0 +1,137 @@
+# Store custom UI kind descriptors
+
+> **Use case id:** `custom-kind-descriptors`
+> **Goal:** Use kindDeclarations / extensions for client-owned tabs without a new engine.
+> **Audiences:** developers
+> **Tags:** metadata, kinds, ui
+
+## Reading path
+
+1. **Metadata, Agents, Abstracts & Mappings** (developers) → chapters: `8-built-in-vs-custom-kinds`
+1. **Agent Packs & Ops** (developers) → chapters: `5-custom-kinds-in-a-pack`
+
+## From: Metadata, Agents, Abstracts & Mappings — 8. Built-in vs custom kinds
+
+Platform engines understand a fixed set of **built-in** kinds, including:
+
+`agents`, `object-types`, `abstract-types`, `abstract-bindings`, `relationships`, `mappings`, `views`, `writes`, `pipelines`, `sources`, `services`, `schedules`, … plus `kind-declarations`.
+
+Clients that need product-specific descriptor families **declare** namespaced custom kinds instead of forking tier-1 code.
+
+| Concern | How |
+|---|---|
+| Declare a kind | `kindDeclarations[]` — id like `acme.ui-tabs`, `name`, `schemaVersion`, optional `itemSchema` |
+| Author items | `extensions["acme.ui-tabs"]` — each item needs `id` |
+| Store / resolve | Same multi-agent inheritance as built-ins (`kind` + `id`) |
+| Catalog | Built-ins keep fixed Catalox catalogs; custom items share `memorix-extensions` |
+| Engines | **Do not** interpret custom kinds — data / relationships / pipelines ignore them |
+
+**Kind id rules:**
+
+- Dotted lowercase namespace (`acme.ui-tabs`)
+- Not a built-in id
+- Not a forbidden operational id (`pipeline-runs`, `leases`, …)
+
+### Worked example
+
+Pack fragment (see also [`memorix-metadata/examples/custom-kinds/acme-ui-tabs.pack.json`](../../../memorix-metadata/examples/custom-kinds/acme-ui-tabs.pack.json)):
+
+```json
+{
+  "kindDeclarations": [
+    {
+      "id": "acme.ui-tabs",
+      "name": "UI Tabs",
+      "description": "Client-owned tab layouts for object detail screens (store/resolve only).",
+      "schemaVersion": "acme.uiTabs.v1",
+      "itemSchema": {
+        "type": "object",
+        "required": ["id", "title", "objectType"],
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "objectType": { "type": "string" },
+          "tabs": { "type": "array" }
+        }
+      }
+    }
+  ],
+  "extensions": {
+    "acme.ui-tabs": [
+      {
+        "id": "employee-detail",
+        "title": "Employee detail",
+        "objectType": "employees",
+        "schemaVersion": "acme.uiTabs.v1",
+        "tabs": [
+          { "id": "overview", "label": "Overview" },
+          { "id": "history", "label": "History" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### HTTP for kinds
+
+```http
+GET /api/metadata/kinds
+GET /api/metadata/kinds/acme.ui-tabs
+GET /api/metadata/definition?kind=acme.ui-tabs&id=employee-detail
+```
+
+`GET /api/metadata/kinds` returns `builtIn` registry rows plus effective `custom` kind-declarations for the scope. Studio browsing for custom kinds may lag the API — treat HTTP as the source of truth today.
+
+---
+
+## From: Agent Packs & Ops — 5. Custom kinds in a pack
+
+When a client needs a descriptor family that is **not** a built-in kind, declare it on the pack and ship items:
+
+```json
+{
+  "format": "memorix-metadata/1",
+  "agentId": "ops",
+  "kindDeclarations": [
+    {
+      "id": "acme.ui-tabs",
+      "name": "UI Tabs",
+      "schemaVersion": "acme.uiTabs.v1"
+    }
+  ],
+  "extensions": {
+    "acme.ui-tabs": [
+      {
+        "id": "employee-detail",
+        "title": "Employee detail",
+        "objectType": "employees"
+      }
+    ]
+  }
+}
+```
+
+Full worked pack: [`memorix-metadata/examples/custom-kinds/acme-ui-tabs.pack.json`](../../../memorix-metadata/examples/custom-kinds/acme-ui-tabs.pack.json).
+
+### Rules of thumb
+
+| Rule | Detail |
+|---|---|
+| Namespaced ids | `vendor.feature` (e.g. `acme.ui-tabs`) |
+| Inheritance | Child agents may override items by same `kind` + `id` |
+| Parent kinds | A child pack may reference a kind declared on an already-installed parent |
+| Execution | Custom kinds are **store/resolve only** — pipelines and the data plane do **not** execute them |
+| Prefer built-ins | Use object types, views, and writes for Memorix-native shape; custom kinds for client-owned descriptors |
+
+Read back via effective metadata / `GET /api/metadata/kinds` after install.
+
+---
+
+## Also see
+
+- **Workflow & Studio** (`09-workflow-and-studio`) — Design · Operate · Explore — scope bar ≡ headers, workflow siblings, embedding guidance. Builders primary.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/data-journey-evidence.md

@@ -0,0 +1,115 @@
+# Use data-journey matrix and evidence APIs
+
+> **Use case id:** `data-journey-evidence`
+> **Goal:** Drive Explore/evidence UIs via /api/data-journey without inventing coverage rules.
+> **Audiences:** developers
+> **Tags:** data-journey, evidence, http
+
+## Reading path
+
+1. **Runtime Data Client** (developers) → chapters: `17-operational-clients`
+1. **Data Access Patterns** (developers) → chapters: `19-observability`, `2-master-decision-matrix`
+
+## From: Runtime Data Client — 17. Operational clients
+
+Operational artifacts are **not** subject records.
+
+Clients may:
+
+- Start pipeline runs; inspect runs and step attempts
+- Retry failed steps; resume runs
+- Retrieve DataRef / artifacts
+- Inspect captured run context
+- Inspect Memory pulls and quarantine
+- Inspect relationship verify/rebuild reports
+- Inspect intelligence **proposals** (never auto-install)
+
+Route families: `/api/pipelines` · `/api/memory` · `/api/relationships` · `/api/intelligence` · `/api/operations` · `/api/data-journey`.
+
+### Data journey (evidence / Explore)
+
+Read-only family for evidence cones and expected-vs-filled coverage (views as **slots only** — descriptors never invent available cells):
+
+| Method | Path | Use |
+|---|---|---|
+| `GET` | `/api/data-journey/object-types` | Selector from effective metadata |
+| `GET` | `/api/data-journey/journeys` | Real runs (+ fixture option when exposed) |
+| `POST` | `/api/data-journey/matrix/query` | Sparse DB/SVC matrix from evidence |
+| `POST` | `/api/data-journey/coverage` | Expected (views) − filled (evidence) |
+| `GET` | `/api/data-journey/expected-slots` | Descriptor slots only |
+| `GET` | `/api/data-journey/evidence/:ref` | Cell drill-down (values opt-in) |
+
+Full Memory → pipeline → client-read narrative: [docs/runtime-data-journey.md](../../../docs/runtime-data-journey.md) (Act V). Package notes: `@x12i/memorix-data-journey` — remote apps call HTTP only.
+
+### Partial failure
+
+Do not blindly re-run an entire pipeline when one step failed — use the retry/resume operations for the failed step/run.
+
+### Intelligence
+
+Proposals are suggestions. Humans (or explicit install APIs) install metadata. Agents must not treat a proposal as already-published truth.
+
+### Ops example
+
+1. Memory pull lands Alex raw from ops-source.
+2. Pipeline run promotes snapshot; one step fails validation.
+3. Retry **that** step; retrieve artifact for the failed attempt.
+4. Read the promoted (or still-raw) content via `/api/data` — do not confuse the artifact with the subject record.
+5. Optionally query `/api/data-journey/coverage` for the same org/agents to see expected slots vs filled evidence.
+
+---
+
+## From: Data Access Patterns — 19. Observability
+
+Every client pattern should carry enough identity to debug without opening Mongo:
+
+- Correlation / request ID
+- Run ID where async
+- Step / attempt ID
+- `recordId` / content address
+- Expected and result revision
+- `sourceId` / `pullId` where Memory
+- `relationshipDefinitionId` where relationship operation
+- Artifact reference where applicable
+
+**Do not log:** credentials, unrestricted raw payloads, sensitive provider data unnecessarily, Mongo connection details.
+
+---
+
+## From: Data Access Patterns — 2. Master decision matrix
+
+For every runtime goal: preferred method, acceptable ad-hoc, forbidden method, and the consistency / retry story.
+
+| Goal | Best | Acceptable | Forbidden | Consistency / retry |
+|---|---|---|---|---|
+| Read one known content instance | Service `GET /api/data/content` (exact) | In-process `@x12i/memorix-data` `getContent` | Mongo `findOne` | Current revision; retry transient failures |
+| Find records matching fields | Bounded list/query + opaque cursor | Temporary ad-hoc filter with hard limit | Unbounded `listAll` / decoded cursors | Cursor contract; retry **same** query+cursor |
+| Read all content about one subject | Explicit composition | Two–three independent exact gets | Flatten siblings into the snapshot; invent `associated*` | Current siblings; per-sibling revisions |
+| Read a union such as People | Abstract list / get | Concrete lists + UI label (diagnosis only) | Abstract collection / abstract `recordId` | Metadata-dependent projection |
+| Follow relationships | Relationship query / `expandRelationships` | Bounded investigation queries | Client-side org-wide joins; copied payloads | Current targets; unresolved stays unresolved |
+| Read current related properties | Related-property / expansion APIs | Two bounded queries | Persist expanded targets on the source | Current; may go stale if cached naïvely |
+| Process a small known set | Batch get (if exposed) or bounded list of addresses | Parallel exact gets with concurrency cap | Cartesian fan-out | Per-item |
+| Process a large set | Pipeline + DataRef | Async export for reporting | Interactive mega-list | Captured/ledgered; retry failed items |
+| Import external data | Memory pull → raw | Controlled source test via Memory | Direct snapshot insert from connector | Source cursor; resume committed cursor |
+| Write one content instance | `patch` / `upsert` / `replace` / `remove` + precondition | Operator script through the same API | Blind replace; Mongo update | Exact revision; never blind-retry after stale |
+| Update an abstract property | `patchAbstract` reverse write | Temporary concrete patch when mapping is clear | Writing an “abstract record” | Maps to one concrete revision |
+| Modify many records | Pipeline / batch with per-item revisions | Capture-all-then-write for tiny sets | Client update-many; list-mutate active sort | Partial success ledger |
+| Create relationships | Relationship engine (discover / materialize / rebuild) | Dry-run / verify | Manual link inserts; `associated*` | Idempotent materialization |
+| Inspect execution history | Operations / pipeline / Memory APIs | Studio Operate views | Treating ledgers as subject content | Operational identity |
+| Inspect evidence / expected slots | `/api/data-journey/*` (matrix, coverage, evidence) | Studio Explore evidence UI | Inventing cells; treating journey rows as subject content | Read-only; views = slots only |
+| Export large data | Asynchronous export artifact | Paginated offline consumer with checkpoint | Single-request dump | Export contract |
+| Investigate once | Bounded ad-hoc API query | Studio Explore | Direct Mongo shell | Read-only unless labeled write |
+| Save a repeated query | Metadata-defined view | Temporary client query | Hardcoded DB query in the product | Versioned with metadata |
+| Repeated business process | Pipeline definition | Scheduled Memory + pipeline | UI-embedded “batch engine” | Durable run ledger |
+| Propose new object type | Intelligence proposal → human install | Export draft for review | Intelligence auto-publish / AI writing records | Proposal ≠ live metadata |
+| Secret to connector | `credentialRef` | — | Secret in body / Memory payload | Never log credentials |
+
+---
+
+## Also see
+
+- **Lists, Queries, Pagination** (`03-lists-queries-pagination`) — List contracts, query grammar, cursors, page size, and multi-resource listing without foot-guns.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/discriminated-content-writes.md

@@ -0,0 +1,152 @@
+# Write analysis / decision / narrative content
+
+> **Use case id:** `discriminated-content-writes`
+> **Goal:** Use discriminators correctly for sibling content types.
+> **Audiences:** developers
+> **Tags:** discriminators, writes, http
+
+## Reading path
+
+1. **Runtime Data Client** (developers) → chapters: `11-discriminated-content-writes`
+1. **Format for Dummies** (developers) → chapters: `10-discriminated-content-instances`
+1. **Data Access Patterns** (developers) → chapters: `15-workflow-analysis-and-decision-content`
+
+## From: Runtime Data Client — 11. Discriminated content writes
+
+Multi-instance content is addressed by:
+
+```ts
+{
+  recordId: string;
+  contentType: string;
+  discriminatorPath: string;   // from content profile metadata
+  discriminatorValue: string;  // e.g. "capacity"
+}
+```
+
+### Rules
+
+1. Discriminator metadata comes from the **content profile**.
+2. Default (if any) is applied **before** addressing and is **persisted**.
+3. Missing required discriminator fails **before** reservation.
+4. Explicit default and omitted-with-default identify the **same** instance.
+5. Discriminator **cannot** be changed with patch/replace — remove then add.
+6. Each discriminator instance has an **independent** revision.
+7. Internal storage key is **not** a client identifier.
+
+### Ops examples
+
+| Case | Behavior |
+|---|---|
+| Two analyses on `wi-100` (`capacity`, `delivery-risk`) | Two instances, two revisions |
+| Different decision types | Separate instances under `decisions` |
+| Duplicate discriminator add | Conflict / duplicate — read existing |
+| Missing required discriminator | Fail before write |
+| Patch that changes discriminator | Immutable failure |
+
+```bash
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  "$BASE/api/data/content?objectType=work-items&contentType=analysis&id=wi-100&discriminator=capacity"
+```
+
+```ts
+await writeContent({
+  op: "add",
+  objectType: "work-items",
+  contentType: "analysis",
+  recordId: "wi-100",
+  discriminatorValue: "capacity",
+  precondition: { kind: "absent" },
+  record: {
+    format: "memorix-record/2",
+    recordId: "wi-100",
+    objectType: "work-items",
+    contentType: "analysis",
+    dataCategory: "entity",
+    data: { kind: "capacity", score: 0.72 },
+  },
+});
+```
+
+---
+
+## From: Format for Dummies — 10. Discriminated content instances
+
+### Why some content types have more than one instance
+
+Analysis, decisions, and discovery can exist many times per subject (capacity vs delivery-risk; priority vs schedule; …).
+
+### Built-in discriminator paths (defaults)
+
+| Content type | Path | Default |
+|---|---|---|
+| `analysis` | `data.analysisType` | `"default"` |
+| `decisions` | `data.decisionType` | `"default"` |
+| `discovery` | `data.discoveryType` | `"default"` |
+
+Metadata defines path / requiredness / default / allowed values. Defaults are applied and **persisted** before addressing so the record stays self-describing.
+
+### Addressing
+
+Same `recordId` + `contentType` + discriminator value → one instance.
+
+- Discriminator values are **immutable** for an existing instance.
+- Changing the discriminator requires **remove + add**.
+- Each instance has its own revision.
+- Mongo’s deterministic storage key is internal; `recordId` remains the subject.
+
+### Two analyses on one work item
+
+```json
+{
+  "recordId": "wi-100",
+  "contentType": "analysis",
+  "data": { "analysisType": "delivery-risk", "risk": "low" }
+}
+```
+
+```json
+{
+  "recordId": "wi-100",
+  "contentType": "analysis",
+  "data": { "analysisType": "capacity", "load": "nominal" }
+}
+```
+
+Validation: missing required discriminator → `V2-DISCRIMINATOR`. Missing with default → warning `V2-DISCRIMINATOR-DEFAULT` (writers apply default).
+
+---
+
+## From: Data Access Patterns — 15. Workflow, analysis, and decision content
+
+### Workflow
+
+Workflow is ordinary sibling content about the subject — not a separate persistence product.
+
+**Best:** exact workflow read; patch/replace with revision; explicit composition for subject context; pipeline/workflow operation for repeated transitions.  
+**Ad-hoc:** one revision-safe workflow correction.  
+**Forbidden:** workflow-specific direct collection writes; flattening workflow into snapshot; a second “workflow service” with different semantics.
+
+### Analysis, decision, discovery
+
+- Discriminator required/default rules come from metadata profiles
+- Multiple instances per subject are normal
+- Exact addressing + independent revisions
+- List by discriminator when discovering instances
+- No in-place discriminator change (remove + recreate when the product allows)
+- Outputs from AI/services are still ordinary V2 content once written
+
+**Best:** pipeline produces a validated typed instance; clients read exact type or list instances.  
+**Ad-hoc:** revision-safe correction of one existing instance if product rules allow.
+
+---
+
+## Also see
+
+- **Workflow & Studio** (`09-workflow-and-studio`) — Design · Operate · Explore — scope bar ≡ headers, workflow siblings, embedding guidance. Builders primary.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/embed-studio-host.md

@@ -0,0 +1,165 @@
+# Embed Studio in a host app
+
+> **Use case id:** `embed-studio-host`
+> **Goal:** Map scope bar to HTTP headers and embed the sole product UI correctly.
+> **Audiences:** developers
+> **Tags:** studio, embedding
+
+## Reading path
+
+1. **Workflow & Studio** (developers) → chapters: `1-studio-constraint-service-only-ui`, `3-scope-bar-http-headers`, `7-embedding-guidance-for-host-apps`
+
+## From: Workflow & Studio — 1. Studio constraint (service-only UI)
+
+`@x12i/memorix-studio` is the **sole Memorix product UI**. It talks **only** to `@x12i/memorix-service` via proxied `/api` and `/health`.
+
+Rules:
+
+1. Do **not** point custom UIs at package internals (`memorix-data`, Mongo drivers, metadata JSON on disk).
+2. Do **not** embed Studio as a shell around direct database access.
+3. Do **not** invent a parallel “admin console” that mutates domain collections.
+4. Host apps that need Memorix capabilities call the **same OpenAPI surface** Studio uses.
+
+### Local run
+
+Prefer the monorepo stack:
+
+```bash
+node scripts/dev-stack.mjs
+# starts ops-source + service + studio + stack-status; opens /_live tabs
+```
+
+Or local pair:
+
+```bash
+# terminal 1 — service (default :5100)
+cd memorix-service && MEMORIX_SERVICE_MODE=dev npm run dev
+
+# terminal 2 — studio (default :5101, proxies to service)
+cd memorix-studio && npm run dev
+```
+
+| Surface | Default |
+|---|---|
+| Studio | http://127.0.0.1:5101 (`MEMORIX_STUDIO_PORT` / `VITE_DEV_PORT`, odd = UI) |
+| Service | http://127.0.0.1:5100 (`MEMORIX_SERVICE_PORT`, even = API) |
+| Service live view | http://127.0.0.1:5100/_live |
+| Stack status | http://127.0.0.1:5103/ |
+| Ops-source | http://127.0.0.1:5102/ (`OPS_SOURCE_PORT`) |
+| Proxy target | `MEMORIX_SERVICE_PROXY_TARGET` or derived from service port |
+
+Zone map: `@x12i/ports-manager` (Memorix **5100–5119**). HTTP compliance: `@x12i/core-service`. Studio binds an **odd** UI port and proxies API via `MEMORIX_SERVICE_PROXY_TARGET` (or derived service port) — it must not bind an even API port. Open for debug: Studio Explore/Operate, service `/_live` (`:5100/_live`), stack hub (`:5103`). Authoring a worker process: [Building Services — HTTP compliance](../../07-services/developers/BOOK.md#http-process-compliance-local-services).
+
+Acceptance workspace: isolated `g12ops*` + `agentIds: ["ops"]` in the scope bar (builders twin shows the screenshot).
+
+### Why this boundary exists
+
+- One auth / scope / revision model for humans and machines.
+- One OpenAPI contract (`GET /api/openapi.json`) for generated clients.
+- No accidental Mongo-shaped writes that bypass directory, G4 relationships, or abstract rules.
+
+---
+
+## From: Workflow & Studio — 3. Scope bar ≡ HTTP headers
+
+Studio’s scope bar is not decoration. It is the same tenant boundary every API call must send.
+
+```http
+x-memorix-org-id: g12ops<suffix>
+x-memorix-agent-ids: ops
+```
+
+| Rule | Detail |
+|---|---|
+| Org | Fresh `g12ops*` for acceptance — never live customer orgs |
+| Agents | Plural header only; comma-separated when multiple |
+| Singular `agentId` | Rejected with **400** |
+| Effective metadata | Resolved for the supplied `agentIds[]` after install |
+
+```bash
+ORG=g12opsdemo01
+H=(-H "x-memorix-org-id: $ORG" -H "x-memorix-agent-ids: ops")
+
+curl -s "${H[@]}" "$SERVICE/api/metadata/effective" | head
+curl -s "${H[@]}" "$SERVICE/health"
+```
+
+If Studio “looks empty,” check scope first — then whether the ops pack is installed for that agent set.
+
+---
+
+## From: Workflow & Studio — 7. Embedding guidance for host apps
+
+When you build a host that embeds Memorix operator flows (or a thin custom panel beside Studio):
+
+### Do
+
+1. **Generate types** from `GET /api/openapi.json` — do not hand-roll divergent envelopes.
+2. **Mirror Studio scope** — same org + `agentIds` headers on every call; surface them in your chrome the way Studio’s scope bar does.
+3. **Mirror Studio IA** — Design / Operate / Explore (or a documented subset). Do not mix “edit metadata” and “edit subject workflow” into one undifferentiated screen without labels.
+4. **Prefer operator widgets** — tables, forms, status chips, confirm dialogs. Hide raw JSON behind “Technical details.”
+5. **Reuse workflow + data + relationships routes** — composition for subject views; `/api/workflow` for review assignment; relationship query for navigation.
+6. **Respect revisions** — never “last write wins” without showing conflict.
+
+### Don’t
+
+| Anti-pattern | Why it fails |
+|---|---|
+| Point UI at Mongo / package internals | Bypasses directory, G4, abstracts, ledgers |
+| Primary UI = raw JSON editor | Operators cannot review safely |
+| Invent a second workflow store | Diverges from composition / KnowX review |
+| Hard-code `fieldstone` / `neo` orgs | Violates isolation hard rules |
+| Singular `agentId` header | Rejected |
+| Auto-install intelligence proposals from a host button labeled “Apply” without confirm | Violates explicit metadata install |
+
+### Minimal host sketch
+
+```ts
+const headers = {
+  "x-memorix-org-id": orgId,           // g12ops…
+  "x-memorix-agent-ids": agentIds.join(","), // ["ops"]
+  "content-type": "application/json",
+};
+
+async function getWorkflow(id: string) {
+  const res = await fetch(`${serviceBase}/api/workflow?id=${encodeURIComponent(id)}`, {
+    headers,
+  });
+  if (!res.ok) throw new Error(`workflowGet ${res.status}`);
+  return res.json();
+}
+
+async function putWorkflow(body: {
+  id: string;
+  expectedRevision: string;
+  record: MemorixRecordV2;
+}) {
+  const res = await fetch(`${serviceBase}/api/workflow`, {
+    method: "PUT",
+    headers,
+    body: JSON.stringify(body),
+  });
+  if (res.status === 409) {
+    // surface conflict UI — re-fetch and retry
+  }
+  if (!res.ok) throw new Error(`workflowPut ${res.status}`);
+  return res.json();
+}
+```
+
+For KnowX human review, sequence:
+
+1. `GET` assertion composition (knowx + workflow + confirmations).
+2. Operator decides accept/reject in UI (not by editing provenance JSON).
+3. Write confirmations sibling + revision-safe patch on knowx epistemic state (book `12`).
+4. Optionally update workflow `state` via `PUT /api/workflow`.
+
+---
+
+## Also see
+
+- **Platform Overview** (`00-platform-overview`) — Surfaces, packages, hard rules, and where to start — developers and builders twins.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._