@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/use-cases/memory-hourly-ingest.md

@@ -0,0 +1,276 @@
+# Ingest an external system on a schedule
+
+> **Use case id:** `memory-hourly-ingest`
+> **Goal:** Land exact provider payloads in Memory, then map/write via pipeline.
+> **Audiences:** developers
+> **Tags:** memory, ingest, pipelines
+
+## Reading path
+
+1. **Relationships & Memory** (developers) → chapters: `2-memory-exact-source-landing`
+1. **Building Pipelines** (developers) → chapters: `1-pipeline-definition`, `13-complete-ops-tutorial`
+1. **Data Access Patterns** (developers) → chapters: `13-memory-as-the-preferred-ingestion-mechanism`
+
+## From: Relationships & Memory — 2. Memory — exact source landing
+
+**Package:** `@x12i/memorix-memory`  
+**HTTP:** `/api/memory`
+
+Memory is a **collector**, not a promoter. It pulls from declared sources and lands **exact** provider payloads as `<objectType>-raw` through `@x12i/memorix-data`.
+
+### Knowledge vs context
+
+| Mode | Retention | Landing | Typical use |
+|---|---|---|---|
+| `knowledge` | Persistent; content-hash dedup | `<objectType>-raw` | Employees, work-items, procedures from ops-source |
+| `context` | Work-scoped TTL / discard | `<objectType>-raw` | Short-lived work-item context pulls |
+
+Both modes land **raw**. Promotion to snapshots (or other subject content) is a **pipeline** concern, not Memory.
+
+### Boundaries (non-goals)
+
+Memory:
+
+- Is **read-only** toward sources (connectors do not mutate the provider).
+- Accepts secrets via **`credentialRef` only** — never raw secrets in request bodies.
+- **Stops at raw handoff** — no promote, no analysis, no relationship discovery inside Memory.
+- Writes operational ledgers in `{orgId}_operational`:
+  - `memory-pull-runs`
+  - `memory-pull-cursors`
+  - `memory-quarantine`
+
+```mermaid
+flowchart LR
+  Src[ops-source] -->|credentialRef| Pull[Memory pull]
+  Pull --> Raw["*-raw via memorix-data"]
+  Pull --> Ledger[operational ledgers]
+  Raw --> Pipeline[Pipelines consume]
+```
+
+### Source declaration (ops pack)
+
+Conceptual source shape:
+
+```json
+{
+  "id": "ops-source",
+  "name": "Ops fixture source",
+  "kind": "rest-fixture",
+  "defaultBaseUrl": "http://127.0.0.1:5102",
+  "credentialRef": "ops-source-local",
+  "endpoints": [
+    "/employees",
+    "/contractors",
+    "/work-items",
+    "/activity-events",
+    "/procedures",
+    "/work-items/:id/context"
+  ]
+}
+```
+
+Studio Design / Operate surfaces sources and pulls:
+
+![Sources / Memory](../screenshots/03-sources-memory.png)
+
+### credentialRef
+
+| Do | Do not |
+|---|---|
+| Reference a configured credential id (`ops-source-local`) | Paste API keys into pull bodies |
+| Rotate credentials in the secret store | Embed secrets in metadata packs checked into git |
+| Fail closed when the ref is missing | Fall back to “temporary plaintext for debugging” in shared orgs |
+
+### Raw landing example
+
+After a knowledge pull for employees, expect content addressed roughly as:
+
+```text
+objectType: employees
+contentType: raw
+recordId:   <stable subject id from source mapping, e.g. alex’s id>
+data:       { …exact provider payload fields per mapping… }
+```
+
+The **exact** bytes (or canonical structured raw) matter later for provenance (`docHash` in KnowX) and for proving what arrived.
+
+### Failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Pull rejected for secrets | Raw secret in body | Use `credentialRef` only |
+| Quarantine entries | Mapping / identity failure on land | Fix source mapping; retry pull |
+| No `*-raw` after “success” | Wrong org/agent scope | Confirm `g12ops*` + `ops` |
+| Expecting snapshots from Memory | Misunderstood boundary | Run the promote pipeline |
+
+### Tutorial-shaped flow
+
+See [documentation/tutorials/04-memory-and-pipeline.md](../../../documentation/tutorials/04-memory-and-pipeline.md):
+
+```text
+Source → /api/memory → *-raw → /api/pipelines → snapshots → /api/data
+```
+
+---
+
+## From: Building Pipelines — 1. Pipeline definition
+
+### Identity
+
+- Stable pipeline metadata ID (`pipelineId`) belongs to an agent (e.g. `ops`).
+- Inheritance and child replacement follow multi-agent metadata rules.
+- Pipeline ID is **not** a run ID.
+- Metadata does not hold runtime state; fingerprints and build evidence live on the run.
+- Do not invent unsupported metadata-version machinery beyond what the runtime captures.
+
+### Scope
+
+Every run uses:
+
+```ts
+{
+  orgId: string;      // e.g. g12ops7a3c — complete data universe
+  agentIds: string[]; // e.g. ["ops"] — effective metadata only
+}
+```
+
+Scope is captured on the run. Every step receives the same canonical scope. Steps must not reinterpret scope. `agentIds` does not filter organization data.
+
+```http
+x-memorix-org-id: g12ops7a3c
+x-memorix-agent-ids: ops
+```
+
+### Definition fields (runtime)
+
+Core runtime shape (`PipelineDefinition` in `@x12i/memorix-pipeline`):
+
+```ts
+type PipelineDefinition = {
+  pipelineId: string;
+  version: string;
+  description?: string;
+  steps: StepDefinition[];
+  services?: ServiceRef[];
+  schedules?: ScheduleDefinition[];
+  retryPolicy?: RetryPolicy;
+  dataRefThresholdBytes?: number; // default 1_048_576
+  metadata?: Record<string, unknown>;
+};
+
+type StepDefinition = {
+  stepId: string;
+  stepKind: StepKind;
+  label?: string;
+  dependsOn?: string[];
+  inputs?: DataRefExpr[];
+  outputKey?: string;
+  retryPolicy?: RetryPolicy;
+  idempotencyKeyExpr?: string; // required for mutating steps
+  port?: string;
+  portConfig?: unknown;
+  serviceId?: string;
+  batchSize?: number;
+  atomicBatch?: boolean; // opt-in; rejected unless adapter supports
+  timeoutMs?: number;
+  disabled?: boolean;
+  inputSchema?: unknown;
+  outputSchema?: unknown;
+};
+```
+
+Agent-pack metadata may use a lighter authoring shape (`id`, `name`, `trigger`, `mode`, `steps[]` with `kind` / `serviceId` / `mappingId`). The runtime compiles or binds that into the executable definition. Always validate packs with `@x12i/memorix-metadata` before install.
+
+### Inputs and outputs
+
+**Inputs:** small inline JSON, DataRef/artifact, record/content address, list/query, abstract reference, relationship reference, Memory source/pull reference, captured context, batch manifest, workflow reference, external trigger payload.
+
+**Outputs:** inline result, DataRef, record address/revision, relationship run result, partial batch manifest, external action receipt, workflow/analysis/decision/narrative references, diagnostics.
+
+Prefer references to stored results over copying large payloads into the run ledger. Default DataRef threshold: **1 MiB**.
+
+### DAG and dependencies
+
+Rules:
+
+- Unique `stepId`s
+- `dependsOn` edges; topological execution
+- Fan-out / fan-in and parallelism for independent branches
+- Cycle rejection; unreachable steps rejected at validate
+- Output-to-input via `inputs` DataRef expressions (`fromStep`, `key`, `path`)
+- Disabled steps skipped
+
+Loops are not a graph feature. Repeated work uses batches, retries, schedules, or an explicit redesign — not hidden cycles.
+
+### Control flow (supported)
+
+Sequential execution · parallel independent branches · per-item batch work · short-circuit on terminal failure · continue-on-item-failure for batches · optional/disabled steps · cancellation.
+
+**Unsupported as global features:** cross-service distributed transactions, hidden graph cycles, silent compensation without an explicit step. Atomic batch is **opt-in** and only when the backing port declares support.
+
+---
+
+## From: Building Pipelines — 13. Complete ops tutorial
+
+End-to-end non-cyber drill. Use a **fresh** `g12ops*` org every acceptance run.
+
+1. **Define procedure source** in ops metadata (`ops-source`).
+2. **Define connector** (Memory collect; `credentialRef` only).
+3. **Define knowledge-ingestion pipeline** (`memory-pull` → raw → map → validate → write → relationships).
+4. **Pull procedures**; confirm raw for **PROC-2**.
+5. **Inspect raw** in Explore / data API (`procedures-raw`).
+6. **Promote** selected procedure snapshot via map/validate/`write-record` — never automatic.
+7. **Pull work-item context** for **WI-100** (context mode as configured).
+8. **Normalize** employee/contractor data (mapping and/or normalize service).
+9. **List People** abstract (employees + contractors including **Alex**).
+10. **Materialize assignments** (relationship discover + write).
+11. **Create work-item ↔ procedure relationship** (WI-100 ↔ PROC-2).
+12. **Run enrichment** (priority completion / enrich service).
+13. **Produce analysis** (`analyze` + `analysisType`).
+14. **Produce decision** (`decide` + `decisionType`).
+15. **Generate narrative** (recorded AI adapter acceptable).
+16. **Update workflow** sibling with exact revision.
+17. **Trigger controlled relationship failure** (e.g. break a definition temporarily).
+18. **Retry relationship step only**; confirm records not duplicated.
+19. **Restart runtime** during another run.
+20. **Resume** without repeating completed work.
+21. **Inspect captured context** artifacts vs current data.
+22. **Inspect artifacts** (hashes, sizes, step association).
+23. **Inspect final records/links** in Explore — four-field links, no copied payloads.
+24. **Run scheduled** invocation; confirm schedule history.
+25. **Run on-demand** invocation with explicit input; confirm distinct `runId`.
+
+Tutorial companion narrative: [documentation/tutorials/04-memory-and-pipeline.md](../../../documentation/tutorials/04-memory-and-pipeline.md).
+
+---
+
+## From: Data Access Patterns — 13. Memory as the preferred ingestion mechanism
+
+When data comes from an external source, land it through Memory first.
+
+```text
+source (ops-source)
+  → Memory pull (credentialRef, read-only connector)
+  → exact raw V2 (*-raw)
+  → downstream pipeline maps / validates / writes subject content
+  → optional relationship materialization
+```
+
+**Not:** connector → snapshot collection directly.
+
+Covered concerns: scheduled knowledge pulls, on-demand context pulls, source cursor, exact raw payload, content-hash dedup, TTL/discard for context mode, quarantine, failure followed by successful later pull, `credentialRef` only, read-only source interaction.
+
+Memory stops at raw handoff. Promote, analysis, and relationship discovery belong to pipelines and the relationship engine — not the connector.
+
+**Best:** Memory pull.  
+**Forbidden:** writing `*-raw` or snapshots from a random script that skips Memory and directory rules; secrets in the request body.
+
+---
+
+## Also see
+
+- **Building Services** (`07-services`) — When to build a service, handlers, pipeline invoke, and core-service / ports-manager / api-live-view.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/metadata-before-write.md

@@ -0,0 +1,145 @@
+# Discover effective metadata before writing
+
+> **Use case id:** `metadata-before-write`
+> **Goal:** Load views/writes from /api/metadata so clients do not invent shapes.
+> **Audiences:** developers
+> **Tags:** metadata, http
+
+## Reading path
+
+1. **Runtime Data Client** (developers) → chapters: `3-metadata-discovery-for-runtime-clients`
+1. **Metadata, Agents, Abstracts & Mappings** (developers) → chapters: `7-views-writes-and-the-client-effective-metadata-pattern`, `9-install-and-publish-never-auto`
+
+## From: Runtime Data Client — 3. Metadata discovery for runtime clients
+
+Before constructing reads and writes, discover **effective** metadata for your scope.
+
+Clients typically need:
+
+- Effective object types and content types
+- Data categories and routing implications
+- Discriminator metadata (path, required/default)
+- Property / schema / view descriptors for UI and validation
+- Lifecycle rules where exposed
+- Abstract types and bindings
+- Relationship definitions
+- Mapping / write capabilities relevant to your job
+
+### Raw vs effective
+
+| Kind | Meaning for clients |
+|---|---|
+| Raw pack metadata | What was installed/published |
+| **Effective** metadata | What this `orgId` + `agentIds[]` resolves to *now* |
+
+Prefer effective endpoints for runtime addressing. Inheritance provenance and multi-agent conflict resolution are server concerns; clients should treat conflicts as metadata errors to surface, not silently pick a winner.
+
+### Caching guidance
+
+- **You may** cache effective metadata for the duration of one user operation or short request batch.
+- **You must** invalidate when the org’s metadata fingerprint/checksum changes, or after install/publish.
+- **You must not** hardcode Mongo collection names derived from types.
+- On metadata validation errors, fail closed — do not guess addresses.
+
+### Practical flow
+
+1. `GET /api/openapi.json` — learn operation IDs and schemas.
+2. `GET /api/metadata/...` — resolve kinds, object/content types, abstracts, views (exact paths in OpenAPI).
+3. Confirm discriminator defaults before writing multi-instance content.
+4. Drive list columns and forms from view/property descriptors — do not invent host-side schemas.
+
+### Ops example
+
+For `g12opsabc123` + `ops`, discover that `work-items` exposes `snapshots`, `workflow`, `analysis`, `decisions`; that `People` is an abstract over `employees` ∪ `contractors`; that relationship definition `employee-owns-work-item` exists. Only then address `wi-100` or Alex.
+
+```bash
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  "$BASE/api/metadata/kinds" | head
+```
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 7. Views, writes, and the client effective-metadata pattern
+
+Integrators should not invent list columns or write forms in the host. Load effective metadata, then drive UI from descriptors.
+
+### Pattern
+
+```text
+1. Resolve effective metadata for (orgId, agentIds[])
+2. Read views / writes / objectTypes / abstracts / custom kinds
+3. Render UI columns and forms from those descriptors
+4. Address data only with concrete types (or abstract reverse-write)
+5. Never bypass the service with direct Mongo domain writes
+```
+
+Example client sketch:
+
+```ts
+const effective = await fetch("/api/metadata/effective", {
+  headers: {
+    "x-memorix-org-id": orgId, // g12ops…
+    "x-memorix-agent-ids": "ops",
+  },
+}).then((r) => r.json());
+
+const employeeSnapshotWrite = effective.writes.find(
+  (w) => w.id === "ops-employees-snapshots",
+);
+
+// Drive form identity / required fields from employeeSnapshotWrite
+// Then POST/PATCH via /api/data against objectType: "employees", contentType: "snapshots"
+```
+
+### Built-in views / writes vs custom kinds
+
+Prefer built-in `views` and `writes` when the need is first-class Memorix shape or Studio-compatible UI composition. Use **custom kinds** (next chapter) when another client owns a descriptor vocabulary the platform should only store and resolve.
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 9. Install and publish — never auto
+
+Hard product behavior: **Intelligence may propose metadata. Install/publish is always an explicit human or API step.**
+
+![Explicit metadata installation](../screenshots/19-explicit-metadata-installation.png)
+
+### Why never auto-install
+
+- Metadata changes change what engines will run next.
+- Accidental install on a shared org is a production incident.
+- Proposals can be wrong, incomplete, or unsafe — review is the product.
+
+### Routes
+
+| Route | Meaning |
+|---|---|
+| `POST /api/metadata/validate` | Check a pack without making it live |
+| `POST /api/metadata/install` | Install into the org metadata DB for the scoped agents |
+| `POST /api/metadata/publish` | Publish / promote a validated set per product policy |
+| `GET /api/metadata/packs` | List known packs |
+
+`@x12i/memorix-metadata-runtime` is the in-process helper behind those routes. Host apps that only talk HTTP never need to import it.
+
+### Ops acceptance flow
+
+1. Start fresh `g12ops*` + `agentIds: ["ops"]`.
+2. Validate the ops pack (or the subset you are changing).
+3. Install explicitly.
+4. Fetch `/api/metadata/effective` and confirm `People`, `work-items`, relationship definitions, sources.
+5. Only then run Memory / pipelines / relationship verify.
+
+If an intelligence proposal looks wrong, **reject it**. Do not install “to see what happens” on a shared org.
+
+Full propose / profile / artifact flow (how proposals are produced and reviewed): [Structural Intelligence](../../10-intelligence/developers/BOOK.md). This book only owns the **install boundary**: proposals are never live until an explicit install/publish.
+
+---
+
+## Also see
+
+- **Structural Intelligence** (`10-intelligence`) — Profile data, proposals with evidence, human install boundary.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/migrate-associated-star.md

@@ -0,0 +1,159 @@
+# Migrate associated* present format to V2
+
+> **Use case id:** `migrate-associated-star`
+> **Goal:** Reject associated* payloads and migrate envelopes with memorix-format tooling.
+> **Audiences:** developers
+> **Tags:** migration, format
+
+## Reading path
+
+1. **Migration & Troubleshooting** (developers) → chapters: `1-present-memorix-record-2`, `2-associated-rejection-what-v2-forbids`, `12-associated-migration-table-detail`, `14-sample-migrate-cli-session`
+
+## From: Migration & Troubleshooting — 1. Present → memorix-record/2
+
+### CLI
+
+```bash
+npx memorix-format migrate-to-v2 ./present.json \
+  --object-type=work-items \
+  --content-type=snapshots \
+  --data-category=entity \
+  --issuer=ops-source
+```
+
+### Library
+
+`migratePresentToV2(present, options) → { ok, v2, extractedRelationships, warnings }`
+
+| Output | Meaning |
+|---|---|
+| `v2` | Clean V2 envelope — **no** copied associated payloads |
+| `extractedRelationships` | Out-of-band candidates — **not** auto-persisted |
+| `warnings` | Timestamp defaults, dropped roots, quarantine notes, … |
+| `ok` | A V2 envelope was produced (may still need validate + link materialization) |
+
+Always:
+
+```bash
+npx memorix-format validate-v2 ./out-v2.json
+# or validateMemorixRecordV2(result.v2)
+```
+
+### Behavior highlights (Format §§18–19)
+
+- Copied related payload removed (`droppedPayloadKeys` on extracted candidates).
+- Resolvable `recordId` links preserved out-of-band (`mapped` / pending metadata).
+- Unresolvable associations quarantined or dropped with status — not silently invented as subjects.
+- `_extIdentifier` → primary identifier (`kind` + `value`).
+- Missing timestamps default with warnings.
+- Subject `_graphRuns` / similar dropped (ops ledgers own history).
+- Present format remains **migration input**, not target truth.
+
+Optional map when you know definition ids:
+
+```ts
+associatedPropertyMap: {
+  associatedPeople: "people-assigned-to-work-items",
+}
+```
+
+---
+
+## From: Migration & Troubleshooting — 2. `associated*` rejection (what V2 forbids)
+
+### Present world (legacy)
+
+Root buckets like `associatedPeople` often held **copied** related records (names, titles, nested `.data`). That caused staleness and unsafe writes.
+
+### V2 / production writer world
+
+| Shape | Format validate | Production writer |
+|---|---|---|
+| Copied payloads under `associated*` | **Reject** (`V2-ASSOC-COPIED`) | Reject (`WRITE_G4_*`) |
+| Lightweight refs only (`relationshipDefinitionId` + `recordId`) | May be format-valid (Option A / migration compat) | **Not** authoritative storage — prefer central links |
+| Four-field relationship link in category store | N/A (separate collection) | **Authoritative** navigation |
+
+```json
+// BAD — copied payload (rejected)
+{
+  "associatedPeople": [
+    {
+      "recordId": "employee-10",
+      "title": "Alex",
+      "data": { "email": "alex@example.com" }
+    }
+  ]
+}
+```
+
+```json
+// GOOD — central link (conceptual)
+{
+  "relationshipId": "…deterministic…",
+  "relationshipDefinitionId": "people-assigned-to-work-items",
+  "fromRecordId": "wi-100",
+  "toRecordId": "employee-10"
+}
+```
+
+Migration extracts candidates **out-of-band**. You must still run relationship discover/verify/rebuild (or pipeline relationship-write) to persist links. Do not paste candidates back onto the V2 snapshot as fat `associated*`.
+
+---
+
+## From: Migration & Troubleshooting — 12. Associated* migration table (detail)
+
+| Input | V2 record | `extractedRelationships` |
+|---|---|---|
+| Item with `recordId` (+ copied fields) | `associated*` removed | status `mapped` or `pending-metadata-resolution`; `droppedPayloadKeys` lists copies |
+| Item without target `recordId` | removed | `quarantined-missing-recordId` |
+| Non-array `associated*` | removed | warning; skipped |
+
+Copied payload is **never** written onto V2. Resolvable links are **never** silently discarded — they leave as out-of-band candidates.
+
+Success vs failure:
+
+- Migration can succeed **with warnings** when a V2 envelope is produced (`ok: true`) even if relationships are pending/quarantined.
+- Callers must still `validateMemorixRecordV2(result.v2)`.
+- Migration does not throw merely because an association target is missing; it quarantines.
+
+Gate G4 reminder: authoritative physical relationship storage is the centralized org-prefixed per-category `relationships` collection — not Option A roots on snapshots.
+
+---
+
+## From: Migration & Troubleshooting — 14. Sample migrate CLI session
+
+```bash
+# 1) migrate
+npx memorix-format migrate-to-v2 ./fixtures/present-wi-100.json \
+  --object-type=work-items \
+  --content-type=snapshots \
+  --data-category=entity \
+  --issuer=ops-source \
+  > ./out/migrate-wi-100.json
+
+# 2) extract v2 document from tool output (shape depends on CLI pretty-print)
+# validate the v2 object:
+npx memorix-format validate-v2 ./out/wi-100-v2.json
+
+# 3) write via service into fresh org
+ORG=g12opsmig01
+H=(-H "x-memorix-org-id: $ORG" -H "x-memorix-agent-ids: ops")
+curl -s "${H[@]}" -X POST "$SERVICE/api/metadata/install" \
+  -H "content-type: application/json" \
+  -d '{"packId":"ops","confirm":true}'
+curl -s "${H[@]}" -X PUT "$SERVICE/api/data/content" \
+  -H "content-type: application/json" \
+  -d @./out/wi-100-write-body.json
+```
+
+Do not skip validate. Do not write present envelopes to the data plane as if they were V2.
+
+---
+
+## 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/openapi-typed-client.md

@@ -0,0 +1,78 @@
+# Orient on OpenAPI / typed clients
+
+> **Use case id:** `openapi-typed-client`
+> **Goal:** Find OpenAPI generation workflow and keep clients aligned with the service.
+> **Audiences:** developers
+> **Tags:** openapi, client
+
+## Reading path
+
+1. **Workflow & Studio** (developers) → chapters: `8-relation-to-data-plane-and-openapi`, `12-openapi-generation-workflow`
+1. **Platform Overview** (developers) → chapters: `4-api-families`
+
+## From: Workflow & Studio — 8. Relation to data plane and OpenAPI
+
+| Need | Prefer |
+|---|---|
+| Generic content CRUD / list / compose | `/api/data/*` |
+| Operator workflow edit | `/api/workflow` |
+| Metadata design | `/api/metadata/*` |
+| Runs / attempts | `/api/pipelines/*` |
+| Contract discovery | `GET /api/openapi.json` |
+
+Workflow writes still obey V2 validation, directory identity, and revision preconditions. The dedicated route does not create a side channel around the data plane — it is a **narrow façade** for a common operator content type.
+
+---
+
+## From: Workflow & Studio — 12. OpenAPI generation workflow
+
+1. Run service locally (`dev-stack` or `memorix-service` alone).
+2. Fetch `GET /api/openapi.json`.
+3. Generate TypeScript (or other) clients with your org’s generator.
+4. Prefer generated `workflowGet` / `workflowPut` operationIds over hand-rolled paths.
+5. Regenerate when service OpenAPI changes — do not forever-pin a stale client against Studio.
+
+Smoke after regenerate:
+
+```bash
+curl -s "$SERVICE/api/openapi.json" | jq '.paths["/api/workflow"] | keys'
+```
+
+Expect `get` and `put`. Treat other workflow-adjacent needs (list by assignee, bulk assign) as **product features on top of** sibling content — not as a reason to invent a second store.
+
+---
+
+## From: Platform Overview — 4. API families
+
+Base: running `memorix-service`. OpenAPI: `GET /api/openapi.json`.
+
+| Prefix | Purpose |
+|---|---|
+| `/api/metadata` | Agents, types, abstracts, install/publish, effective resolution |
+| `/api/data` | Content get/list/compose, abstract get/list/patch, writes |
+| `/api/relationships` | Verify/rebuild/query (no ad-hoc link PUT/DELETE) |
+| `/api/memory` | Pulls, cursors, quarantine (`credentialRef` only for secrets) |
+| `/api/pipelines` | Definitions, runs, retries, artifacts |
+| `/api/intelligence` | Profiles and proposals (never auto-installs) |
+| `/api/workflow` | Workflow sibling content + assignments |
+| `/api/operations` | Operational health / ops helpers |
+
+### Writes
+
+Require scope + revision precondition (`absent` or exact `revision`). Stale revision → conflict (`409`).
+
+### Prefer HTTP over libraries
+
+Remote hosts should call **service HTTP**. Install `@x12i/memorix-data` / relationships / pipeline only inside the same trusted process boundary as the platform. Never write domain records with raw Mongo drivers.
+
+Deep dive: [Runtime Data Client](../../02-runtime-data-client/developers/BOOK.md) · [Data Access Patterns](../../04-data-access-patterns/developers/BOOK.md).
+
+---
+
+## Also see
+
+- **Runtime Data Client** (`02-runtime-data-client`) — Connection, scope, exact reads, writes, compose, abstracts, and client anti-patterns through Memorix Service / OpenAPI.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._