@x12i/memorix-docs 1.0.2 → 1.1.0

package/files/use-cases/studio-review-intelligence.md

@@ -0,0 +1,74 @@
+# Review intelligence proposals in Studio
+
+> **Use case id:** `studio-review-intelligence`
+> **Goal:** Accept evidence, reject bad proposals, install only deliberately.
+> **Audiences:** builders
+> **Tags:** studio, intelligence
+
+## Reading path
+
+1. **Structural Intelligence** (builders) → chapters: `1-where-in-studio`, `2-what-good-evidence-looks-like`, `3-review-reject-install-checklist`
+
+## From: Structural Intelligence — 1. Where in Studio
+
+| Need | Go to |
+|---|---|
+| Run / inspect profiling | Operate → intelligence runs (and related artifacts) |
+| Read a proposal | Design → intelligence proposals |
+| Install after approval | Design → metadata install / publish |
+| Confirm it took effect | Design → effective types / agents · Explore lists |
+
+Scope bar first: fresh `g12ops*` + agent `ops`. Never rehearse installs on live customer orgs.
+
+---
+
+## From: Structural Intelligence — 2. What “good evidence” looks like
+
+Ask before installing:
+
+1. Were samples **deterministic** (ops fixtures) or a one-off scrape?
+2. Does the proposal explain **paths / types / cardinality**, or only vague labels?
+3. Is anything marked **insufficient evidence** or **rejected by validation**?
+4. Does compare-against-ops show a **small, understandable** diff?
+5. Will this change writers/readers for Alex / WI-100 in ways you can explain?
+
+If you cannot answer those, **reject** (or request more fixtures). Rejection is a successful outcome.
+
+---
+
+## From: Structural Intelligence — 3. Review → reject → install checklist
+
+### Review
+
+- [ ] Scope is `g12ops*` + `ops`
+- [ ] Proposal id / timestamp recorded
+- [ ] Evidence section opened (not only summary chips)
+- [ ] Compare against approved `ops` (when available)
+- [ ] AI-only suggestions flagged as untrusted extras
+
+### Reject when
+
+- Evidence is thin or contradictory
+- Diff invents cyber/vendor vocabulary into the permanent ops narrative
+- Validation already rejected the draft
+- You are on the wrong org / agent set
+- Someone asks you to “just apply” without reading
+
+### Install only when
+
+- [ ] Human review completed
+- [ ] Explicit install/publish confirmation clicked
+- [ ] Effective metadata refreshed afterward
+- [ ] Explore still shows expected subjects (smoke check WI-100 / Alex)
+
+Install is a **different** action from “generate proposal.” If Studio ever conflates them, treat that as a defect.
+
+---
+
+## Also see
+
+- **Metadata, Agents, Abstracts & Mappings** (`05-metadata-agents-abstracts`) — Agents, OT/CT, virtual abstracts, mappings, install/publish — never auto-install from intelligence.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/studio-scope-isolation.md

@@ -0,0 +1,67 @@
+# Keep workspaces isolated via the scope bar
+
+> **Use case id:** `studio-scope-isolation`
+> **Goal:** Never mix orgs/workspaces; treat scope as the product boundary.
+> **Audiences:** builders
+> **Tags:** studio, scope, isolation
+
+## Reading path
+
+1. **Workflow & Studio** (builders) → chapters: `1-scope-bar-first-always`, `6-operator-ux-rules`
+1. **Platform Overview** (builders) → chapters: `6-rules-builders-enforce`, `9-acceptance-workspace`
+
+## From: Workflow & Studio — 1. Scope bar first (always)
+
+![Isolated workspace scope](../screenshots/01-isolated-workspace-scope.png)
+
+Before any meaningful work:
+
+1. Choose a **fresh** `g12ops*` organization (never a live customer org).
+2. Set agent to **`ops`** (or the agent set your pack documents).
+3. Confirm Design / Operate / Explore reflect that scope.
+4. If screens look empty or “wrong types,” fix scope and metadata install before filing a bug.
+
+Forbidden for acceptance drills: legacy/live customer org names. Always `g12ops*` + `ops`.
+
+---
+
+## From: Workflow & Studio — 6. Operator UX rules
+
+| Do | Don’t |
+|---|---|
+| Prefer tables, forms, status, confirmations | Make raw JSON the primary review surface |
+| Open technical JSON only when needed | Ask engineers to “just patch Mongo” |
+| Keep Design / Operate / Explore jobs separate | Mix install, run, and subject edit without labels |
+| Use fresh `g12ops*` for drills | Practice on live customer orgs |
+| Explicit metadata install | Expect intelligence to “just apply” |
+| Capture org, agents, subject, revision, run id on failure | Escalate with only “it broke” |
+
+Studio talks **only** to Memorix Service. If someone claims Studio “writes Mongo,” they are wrong about the architecture.
+
+---
+
+## From: Platform Overview — 6. Rules builders enforce
+
+- Fresh `g12ops*` + agent `ops` for acceptance and drills.
+- No live customer orgs as playgrounds.
+- Relationships never copy the other record’s payload into this one.
+- Abstracts are views — you always write to a **concrete** type.
+- Intelligence proposes; humans install.
+- Deterministic fixtures for acceptance — do not require live AI to prove the platform.
+- When something fails, capture: org, agents, subject id, content type, revision, run/attempt id — then escalate with that packet.
+
+Hard rules (full): [HARD-RULES.md](../../HARD-RULES.md).
+
+---
+
+## From: Platform Overview — 9. Acceptance workspace
+
+Always use a fresh `g12ops*` organization with agent `ops`. Never use live customer orgs for drills. See [_shared/ops-scenario.md](../../_shared/ops-scenario.md).
+
+## Also see
+
+- **Agent Packs & Ops** (`11-agent-packs-and-ops`) — Pack layout, harness, g12ops* acceptance, custom kinds, golden V2 validation.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/studio-stale-conflict-ui.md

@@ -0,0 +1,54 @@
+# Resolve stale conflicts from the UI
+
+> **Use case id:** `studio-stale-conflict-ui`
+> **Goal:** Recognize revision conflicts and recover without losing the other writer’s work blindly.
+> **Audiences:** builders
+> **Tags:** studio, conflicts
+
+## Reading path
+
+1. **Migration & Troubleshooting** (builders) → chapters: `2-stale-conflicts-what-you-should-do`, `4-symptom-where-to-click`
+1. **Format for Dummies** (builders) → chapters: `4-revision-why-saves-sometimes-conflict`
+
+## From: Migration & Troubleshooting — 2. Stale conflicts (what you should do)
+
+When Explore/Workflow save fails because someone else (or you in another tab) saved first:
+
+1. Read the conflict message — do not force-overwrite.
+2. Refresh the subject.
+3. Re-apply **your** intent on the latest revision.
+4. Save again.
+
+This is normal optimistic concurrency — not a broken database.
+
+---
+
+## From: Migration & Troubleshooting — 4. Symptom → where to click
+
+| Symptom | Studio area | Likely next step |
+|---|---|---|
+| Empty types / agents | Design | Explicit metadata install |
+| Proposal didn’t change anything | Design | Review → **install** or reject (by design) |
+| Pull failed / quarantine | Operate → Memory | Fix source/credentialRef; re-pull |
+| Step failed | Operate → Failures / Artifacts | Read artifact; fix mapping/service; retry |
+| Save conflict | Explore | Refresh + retry |
+| Link missing | Operate → Relationships | Verify/rebuild definition |
+| Wrong tenant’s subjects | Scope bar | Fix org / agents |
+
+---
+
+## From: Format for Dummies — 4. Revision (why saves sometimes conflict)
+
+Every content instance has a **revision**. When you save, Studio sends the revision it believes is current. If someone else saved first, you get a **stale conflict** — refresh, re-apply your intent, save again.
+
+That is protection, not a bug. Do not ask for a Mongo force-write.
+
+---
+
+## 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/troubleshoot-http-matrix.md

@@ -0,0 +1,164 @@
+# Troubleshoot runtime HTTP failures
+
+> **Use case id:** `troubleshoot-http-matrix`
+> **Goal:** Use the failure matrix and escalate packet when stuck.
+> **Audiences:** developers
+> **Tags:** troubleshooting, http
+
+## Reading path
+
+1. **Migration & Troubleshooting** (developers) → chapters: `4-failure-matrix-runtime-http`, `11-escalate-packet-for-humans-builders`, `13-end-to-end-repair-playbooks`
+
+## From: Migration & Troubleshooting — 4. Failure matrix (runtime HTTP)
+
+Use this as the first lookup when demos break.
+
+### 409 — stale revision / conflict
+
+| Likely cause | Fix |
+|---|---|
+| Concurrent edit; wrong `expectedRevision` | Re-GET content; merge; retry with current revision |
+| Workflow PUT with stale revision | Same — Studio shows stale conflict UI |
+
+```bash
+# pattern
+curl -s "${H[@]}" "$SERVICE/api/data/content?objectType=work-items&contentType=workflow&id=wi-100"
+# note revision → PUT /api/workflow with expectedRevision
+```
+
+### 405 — relationship link mutation
+
+| Likely cause | Fix |
+|---|---|
+| Ad-hoc PUT/DELETE on links | Use `/api/relationships` verify / rebuild / discover |
+| Host treating links like ordinary documents | Relationship engine only |
+
+### 503 — durable routes unavailable
+
+| Likely cause | Fix |
+|---|---|
+| Prod/durable mode without Mongo | Set `MEMORIX_SERVICE_MODE=prod` + `MONGO_URI` |
+| Service down | Check `/health`; restart `dev-stack` |
+| Port already in use / AirPlay conflict | Avoid **5000/7000**; stay in zone **5100–5119**; see `@x12i/ports-manager` `port-map.json` avoid list (`npx x12i-ports avoid`) |
+
+### Unresolved relationships
+
+| Likely cause | Fix |
+|---|---|
+| Target subject/content missing | Write targets first; or rebuild definition after targets exist |
+| Wrong definition / candidate set | Discover/rebuild for the definition id |
+| Expansion shows `targetStatus: "unresolved"` | **Expected** calculated signal — do not invent fake targets |
+
+### Abstract write error
+
+| Likely cause | Fix |
+|---|---|
+| Treating abstract type as a write collection | Write concrete object types |
+| Non-reversible abstract property | Adjust bindings / use concrete path |
+| Multi-target ambiguity | Disambiguate concrete type / id |
+
+### Intelligence “did nothing”
+
+| Likely cause | Fix |
+|---|---|
+| Expecting auto-install | Explicit `/api/metadata/install` or Studio install |
+| Insufficient evidence | Gather fixtures; do not force install |
+| Wrong org/agent | Fresh `g12ops*` + `ops` |
+
+### Discriminator failures
+
+| Likely cause | Fix |
+|---|---|
+| Missing `data.analysisType` (etc.) when required | Supply value or profile default |
+| Changing immutable discriminator in place | remove old instance + add new |
+
+### Scope / headers
+
+| Symptom | Fix |
+|---|---|
+| 400 on `agentId` | Use plural `x-memorix-agent-ids` |
+| Empty / wrong types | Install pack; fix agent set |
+| Wrong tenant data | Fix `x-memorix-org-id` |
+
+### Memory / pipelines
+
+| Symptom | Fix |
+|---|---|
+| Secret rejected | Pass `credentialRef` only |
+| Raw present, no snapshots | Check pipeline runs & artifacts |
+| Quarantine growing | Inspect mapping / provider shape |
+
+### Stack / networking
+
+| Symptom | Fix |
+|---|---|
+| Studio loads, API fails | Service `:5100/health`; proxy target |
+| Port in use | Change `MEMORIX_*_PORT` (even=API, odd=UI) |
+
+---
+
+## From: Migration & Troubleshooting — 11. Escalate packet (for humans / builders)
+
+When filing or receiving a failure, require:
+
+| Field | Example |
+|---|---|
+| Org id | `g12opsab12cd` |
+| Agent ids | `["ops"]` |
+| Subject / content | `wi-100` / `workflow` |
+| Revision observed | `3` |
+| Route + status | `PUT /api/workflow` → `409` |
+| Run / attempt id | pipeline attempt uuid |
+| Artifact ref | failure artifact id |
+| Fixture mode | deterministic ops-source: yes/no |
+| Screenshot | scope bar + error |
+
+Builders twin turns this into a Studio quick-check list.
+
+---
+
+## From: Migration & Troubleshooting — 13. End-to-end repair playbooks
+
+### Playbook A — Stale workflow edit (409)
+
+1. `GET /api/workflow?id=wi-100` (or data content read).
+2. Diff operator intent against `record.data`.
+3. `PUT /api/workflow` with `expectedRevision` = current.
+4. If 409 again, another writer won — loop once; then escalate with both revisions.
+
+### Playbook B — Missing links after migrate
+
+1. Confirm V2 subjects for endpoints exist (`employee-10`, `wi-100`).
+2. Map extracted candidates → `relationshipDefinitionId` values installed in ops metadata.
+3. `POST /api/relationships/discover` (bounded) and/or pipeline `relationship-write`.
+4. `POST /api/relationships/verify` for the definition.
+5. Expand in compose/query — unresolved targets stay visible if still missing.
+
+### Playbook C — Abstract write confusion
+
+1. Confirm the abstract type is virtual (People).
+2. Choose concrete `objectType` (`employees` / `contractors`) or use documented reverse-map patch APIs.
+3. Never create an abstract collection or abstract `recordId`.
+
+### Playbook D — Intelligence silence
+
+1. Confirm proposal artifact exists (Design / `/api/intelligence/proposals`).
+2. Confirm effective metadata hash unchanged after propose (expected).
+3. Explicit install with confirm — or reject.
+4. Re-check `/api/metadata/effective`.
+
+### Playbook E — 503 on durable routes
+
+1. `GET /health`.
+2. Check `MEMORIX_SERVICE_MODE` and `MONGO_URI` for durable/prod.
+3. Restart `dev-stack` / service; re-try the same scoped call.
+
+---
+
+## 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._

package/files/use-cases/trusted-in-process-embed.md

@@ -0,0 +1,94 @@
+# Embed Memorix engines in a trusted host
+
+> **Use case id:** `trusted-in-process-embed`
+> **Goal:** Know when in-process packages are allowed vs remote HTTP-only clients.
+> **Audiences:** developers
+> **Tags:** embedding, packages
+
+## Reading path
+
+1. **Platform Overview** (developers) → chapters: `5-sixteen-packages-when-to-use-what`, `8-hard-product-rules-integrator-checklist`
+1. **Structural Intelligence** (developers) → chapters: `12-in-process-vs-http`
+
+## From: Platform Overview — 5. Sixteen packages (when to use what)
+
+All of the packages below publish as **`@x12i/memorix-*@3.0.2+`**. HTTP compliance kits (`ports-manager`, `api-live-view`, `core-service`) are separate `@x12i/*` packages.
+
+| Package | Integrator use |
+|---|---|
+| `memorix-format` | Validate / migrate `memorix-record/2` offline |
+| `memorix-metadata` | Declarative contracts + abstract unions |
+| `memorix-metadata-runtime` | Install / effective metadata client (trusted boundary) |
+| `memorix-mapping` | Deterministic mapping AST execution |
+| `memorix-data` | Read/write/compose/abstract (preferred library behind service) |
+| `memorix-relationship-store` | Link storage contract (engine-internal; not for ad-hoc writes) |
+| `memorix-relationships` | Trusted relationship engine |
+| `memorix-memory` | Source pull → `*-raw` landing |
+| `memorix-pipeline` | Pipeline definitions and execution |
+| `memorix-pipeline-runtime` | Run/attempt/artifact ledgers |
+| `memorix-intelligence` | Structural profiling + proposals |
+| `memorix-service` | HTTP composition root |
+| `memorix-studio` | Product UI |
+| `memorix-ops-pack` | Ops metadata + fixtures pattern |
+| `memorix-db-router` | Org/agent DB naming |
+| `memorix-mongo` | Mongo helpers used by data plane |
+
+### Decision tree — HTTP vs package
+
+```text
+Remote host / another product?
+  └─ Yes → call memorix-service HTTP (optional: memorix-format for offline validate)
+Same trusted process as the platform?
+  └─ Yes → may use memorix-data / metadata-runtime / engines in-process
+Need to mutate domain content?
+  └─ Always through data plane (service or memorix-data) — never raw Mongo
+Need to mutate relationship links?
+  └─ Only via relationship engine APIs (verify/rebuild/materialize) — never ad-hoc PUT/DELETE
+```
+
+---
+
+## From: Platform Overview — 8. Hard product rules (integrator checklist)
+
+These invariants apply to every integration, acceptance example, and ebook:
+
+1. Acceptance orgs are fresh `g12ops*` with `agentIds: ["ops"]`.
+2. Permanent narrative is non-cyber **ops** (employees, work-items, procedures).
+3. Relationships are four-field links only — no root `associated*` storage, no copied payloads.
+4. Abstracts are virtual projections — no abstract collections / abstract `recordId`.
+5. KnowX is one content type + `data.kind` (`NODE` | `EDGE`) + one abstract `KnowXEntity`.
+6. Provenance (`docHash` + `SourceSpan`) is mandatory for KnowX; `epistemic.state` ≠ extraction confidence.
+7. Deterministic fixtures only for acceptance — no live AI required.
+8. Mutations go through the data plane (`memorix-service` / `@x12i/memorix-data`), never direct Mongo domain writes.
+
+Full text: [HARD-RULES.md](../../HARD-RULES.md).
+
+---
+
+## From: Structural Intelligence — 12. In-process vs HTTP
+
+| Mode | Use when | Caution |
+|---|---|---|
+| HTTP `/api/intelligence/*` | Remote hosts, Studio, demos | Prefer for product boundaries |
+| In-process `@x12i/memorix-intelligence` | Trusted platform workers | Still must not call install implicitly |
+
+Even in-process, keep proposal creation and metadata install in **separate functions / jobs**. A single “profileAndApply” helper is an anti-pattern.
+
+```ts
+// Good: explicit stages
+const profile = profileRecords(samples, opts);
+const proposal = createProposal(profile, opts);
+// ... persist proposal artifact, notify reviewers ...
+// later, after approval:
+await metadataRuntime.install({ pack: approvedPack, confirm: true, scope });
+```
+
+---
+
+## 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/workflow-sibling-api.md

@@ -0,0 +1,212 @@
+# Work with workflow sibling content via API
+
+> **Use case id:** `workflow-sibling-api`
+> **Goal:** Treat workflow as sibling content under /api/workflow, not a separate product.
+> **Audiences:** developers
+> **Tags:** workflow, http
+
+## Reading path
+
+1. **Workflow & Studio** (developers) → chapters: `4-workflow-is-sibling-content`, `5-workflow-http-api-workflow`
+1. **Runtime Data Client** (developers) → chapters: `16-workflow-clients`
+
+## From: Workflow & Studio — 4. Workflow is sibling content
+
+Workflow is **not** a separate product database and not a Mongo collection you invent. It is ordinary `memorix-record/2` content:
+
+```json
+{
+  "format": "memorix-record/2",
+  "recordId": "wi-100",
+  "revision": 2,
+  "objectType": "work-items",
+  "contentType": "workflow",
+  "dataCategory": "entity",
+  "concept": {
+    "title": "Workflow for WI-100",
+    "identifiers": {
+      "primary": {
+        "kind": "workItemId",
+        "value": "WI-100",
+        "issuer": "ops-source"
+      }
+    }
+  },
+  "data": {
+    "state": "in-progress",
+    "assignedTo": ["ops-reviewers"],
+    "steps": [
+      { "id": "triage", "status": "done" },
+      { "id": "ops-review", "status": "open" }
+    ]
+  },
+  "_system": {
+    "state": "active",
+    "createdAt": "2026-07-22T09:00:00.000Z",
+    "modifiedAt": "2026-07-22T11:00:00.000Z"
+  }
+}
+```
+
+Composition with the same `recordId` yields siblings — for example `work-items-snapshots` + `work-items-workflow` — without flattening.
+
+KnowX review pattern (book `12`): assertions often carry:
+
+- `contentType: "knowx"` — the claim
+- `contentType: "workflow"` — assignment / pending-review
+- `contentType: "confirmations"` — accept/reject decision
+
+Do **not** stuff review UI state into provenance. Use workflow / confirmations siblings.
+
+---
+
+## From: Workflow & Studio — 5. Workflow HTTP (`/api/workflow`)
+
+OpenAPI family: **Workflow**. Two operations mirror Studio Explore workflow edit.
+
+### 5.1 Read — `GET /api/workflow`
+
+```http
+GET /api/workflow?id=wi-100
+x-memorix-org-id: g12ops…
+x-memorix-agent-ids: ops
+```
+
+Response shape (conceptual):
+
+```ts
+{
+  scope: MemorixScope;
+  id: string | null;
+  contentType: "workflow";
+  record: MemorixRecordV2 | null;
+  currentRevision: number | null;
+  note?: string;
+}
+```
+
+Notes:
+
+- `contentType` is fixed to `"workflow"`.
+- Missing workflow returns a null `record` (and null revision) rather than inventing empty steps.
+- You can also read via the data plane (`/api/data/content?objectType=…&contentType=workflow&id=…`). The workflow family exists so operator clients have a stable, narrow contract.
+
+### 5.2 Write — `PUT /api/workflow`
+
+Exact-revision edit (optimistic concurrency):
+
+```http
+PUT /api/workflow
+x-memorix-org-id: g12ops…
+x-memorix-agent-ids: ops
+content-type: application/json
+```
+
+```json
+{
+  "id": "wi-100",
+  "expectedRevision": "2",
+  "record": {
+    "format": "memorix-record/2",
+    "recordId": "wi-100",
+    "revision": 2,
+    "objectType": "work-items",
+    "contentType": "workflow",
+    "dataCategory": "entity",
+    "concept": {
+      "title": "Workflow for WI-100",
+      "identifiers": {
+        "primary": {
+          "kind": "workItemId",
+          "value": "WI-100",
+          "issuer": "ops-source"
+        }
+      }
+    },
+    "data": {
+      "state": "pending-review",
+      "assignedTo": ["ops-reviewers"]
+    },
+    "_system": {
+      "state": "active",
+      "createdAt": "2026-07-22T09:00:00.000Z",
+      "modifiedAt": "2026-07-22T11:00:00.000Z"
+    }
+  }
+}
+```
+
+| Field | Role |
+|---|---|
+| `id` | Subject `recordId` |
+| `record` | Full V2 workflow envelope (`contentType` must be `workflow`) |
+| `expectedRevision` | Exact revision the client believes is current |
+| `currentRevision` (optional) | When set and mismatched, service returns **409** |
+
+Success response (conceptual): `scope`, `id`, `expectedRevision`, `currentRevision`, `status`, `conflict: false`.
+
+Conflict: **409** — re-GET, merge operator intent, retry with the new revision. Studio shows this as a stale-edit conflict (see migration book screenshot `17-stale-conflict`).
+
+### 5.3 Error matrix (workflow-focused)
+
+| Status | Likely meaning | Fix |
+|---|---|---|
+| 400 | Bad body / validation / singular agent header | Fix envelope + plural `agent-ids` |
+| 403 | Forbidden for this scope | Check org / agents / auth |
+| 409 | Stale revision / conflict | Re-read; retry exact revision |
+| 503 | Service unavailable (often durable mode without Mongo) | Set prod mode + `MONGO_URI`, or use documented dev mode |
+
+Always validate locally when iterating:
+
+```bash
+npx memorix-format validate-v2 ./work-items-workflow.json
+```
+
+---
+
+## From: Runtime Data Client — 16. Workflow clients
+
+Workflow is **ordinary sibling content** on the subject.
+
+- Read/write through the data API (and `/api/workflow` as a specialized view of the same rules).
+- Exact revision required for updates.
+- Explicit composition when the UI also needs snapshot/analysis.
+- No separate “workflow database” semantics.
+- Studio workflow surfaces are views over canonical content operations.
+
+### Ops example — edit WI-100 workflow
+
+1. GET workflow sibling for `wi-100` → note `revision`.
+2. PATCH assignee / step with that revision.
+3. On conflict, re-read, merge, retry.
+4. Compose with snapshot when the page shows both status and assignment.
+
+```ts
+async function editWorkflow(recordId: string, nextAssignee: string) {
+  const current = await getContent({
+    objectType: "work-items",
+    contentType: "workflow",
+    recordId,
+  });
+  await writeContent({
+    op: "patch",
+    objectType: "work-items",
+    contentType: "workflow",
+    recordId,
+    precondition: { kind: "revision", revision: current.revision },
+    patch: [{ op: "set", path: "data.assignee", value: nextAssignee }],
+  });
+}
+```
+
+See also [Workflow & Studio](../../09-workflow-and-studio/developers/BOOK.md).
+
+---
+
+## 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/visuals/revision-conflict.md

@@ -0,0 +1,19 @@
+---
+id: "revision-conflict"
+type: "visual"
+title: "Stale writers are rejected; the record stays at the newer revision."
+summary: "Revision preconditions preserve newer data."
+---
+# Stale writers are rejected; the record stays at the newer revision.
+
+Alt: Conflict dialog showing stale expected revision while record remains unchanged
+
+## What to notice
+
+- Expected revision is shown
+- Record was not mutated
+- Recovery is reload and retry
+
+## Why it matters
+
+Revision preconditions preserve newer data.