@x12i/memorix-docs 1.0.1 → 1.1.0

package/files/use-cases/revision-stale-conflicts.md

@@ -0,0 +1,194 @@
+# Handle revision / stale conflicts
+
+> **Use case id:** `revision-stale-conflicts`
+> **Goal:** Patch with revision preconditions and recover when another writer won.
+> **Audiences:** developers
+> **Tags:** revisions, conflicts, http
+
+## Reading path
+
+1. **Runtime Data Client** (developers) → chapters: `10-patch-language`, `18-error-catalog-client-facing`
+1. **Migration & Troubleshooting** (developers) → chapters: `4-failure-matrix-runtime-http`
+
+## From: Runtime Data Client — 10. Patch language
+
+Patches are structured operations with path rules — not free-form JSON Merge Patch against the whole envelope unless the contract says so.
+
+### Typical operations
+
+| Op | Use |
+|---|---|
+| `set` | Set a value at an allowed path |
+| `unset` / remove | Clear an allowed path where supported |
+
+### Path rules (client view)
+
+- Prefer paths under `data`, and allowed `concept` / `_system` subsets per contract.
+- Envelope fields (`format`, `recordId`, `objectType`, `contentType`, …) are immutable via patch.
+- Discriminator values are immutable via patch/replace.
+- Lifecycle modifications follow metadata rules — illegal transitions fail.
+- Concept / data / system ownership is contract-defined; do not invent cross-bucket ownership.
+- Conflicting ops in one request fail validation.
+- Invalid or unsafe paths fail before mutation.
+- Validation runs **after** patch application against V2 + profiles.
+
+### Valid vs invalid (illustrative)
+
+**Valid**
+
+- Set `data.priority` on WI-100 snapshot.
+- Unset an optional `data` field allowed by schema.
+- Set `concept.title` when the profile allows title edits.
+
+**Invalid**
+
+- Set `revision` or `format`.
+- Set discriminator in place.
+- Set root `associatedEmployees` or any `associated*`.
+- Patch Mongo `_id`.
+- Invent `/../../` or injection-shaped paths.
+- Conflicting `set` + `unset` on the same path in one request.
+
+### After patch
+
+Re-read if your client needs the server-normalized record (defaults, timestamps, omitted empty buckets). Do not assume the patch document equals the stored document byte-for-byte.
+
+---
+
+## From: Runtime Data Client — 18. Error catalog (client-facing)
+
+For each error, clients should know: code, HTTP status, whether retryable, whether to refetch, whether the same body may be repeated.
+
+| Situation | Typical status / code class | Client action |
+|---|---|---|
+| Invalid scope / singular `agentId` | `400` | Fix headers; do not retry unchanged |
+| Unknown object/content type | `400` / validation | Rediscover metadata |
+| Missing content | `404` / `READ_NOT_FOUND` | Create with `absent` or show empty UI |
+| Directory identity conflict | conflict / validation | Stop — `recordId` already bound differently |
+| Missing discriminator | validation | Supply required discriminator |
+| Immutable discriminator | validation | Remove then add; do not patch |
+| Duplicate add | conflict | Read existing content |
+| Stale revision | `409` | Refetch, reconcile, retry with new revision |
+| Absent-precondition conflict | conflict | Content already exists — switch to revision write |
+| Immutable envelope | validation | Remove illegal paths from patch |
+| Invalid lifecycle | validation | Follow allowed transitions |
+| Validation failure | `400` | Fix body against schema/profile |
+| Unsafe query / injection-shaped filter | `400` | Rewrite with allowlisted grammar |
+| Cursor mismatch | `400` | Restart list from page 1 |
+| Unsupported abstract pushdown | `400` | Narrow query or query concrete types |
+| Abstract non-reversible / non-member | `400` | Fix abstract write inputs |
+| Relationship query unbounded | `400` | Add bounds / change traversal |
+| Unresolved target | readable state | Show gap; optional later retry |
+| Missing canonical runtime port | platform | Misconfig — not a client retry loop |
+| Artifact not found / wrong org | `404` | Fix org or artifact id |
+| Pipeline partial failure | run status | Retry failed step/run op |
+| Malformed Memory item | quarantine | Inspect quarantine; fix source mapping |
+| Durable route `503` in `dev` without Mongo | `503` | Use `prod` + `MONGO_URI` or accept in-memory limits |
+
+Studio and HTTP both surface these classes; decode the structured error body when present.
+
+### Example — stale write
+
+```text
+PATCH wi-100 snapshots expectedRevision=3
+→ 409 WRITE_STALE_REVISION (current is 4)
+→ GET again → merge → PATCH expectedRevision=4
+```
+
+---
+
+## 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) |
+
+---
+
+## 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/start-from-zero.md

@@ -0,0 +1,171 @@
+# Start Memorix from zero
+
+> **Use case id:** `start-from-zero`
+> **Goal:** Install docs for your agents, set scope, run the stack, and walk the tutorials to the core loop.
+> **Audiences:** developers, builders
+> **Tags:** getting-started, tutorials, start-here
+
+## Reading path
+
+1. **Getting Started & Tutorials** (developers) → chapters: `1-installation-for-agents`, `2-getting-started`, `4-tutorial-run-the-local-stack`, `5-tutorial-first-read-and-write`
+1. **Getting Started & Tutorials** (builders) → chapters: `2-getting-started`, `4-tutorial-run-the-local-stack`, `7-tutorial-memory-to-pipeline`
+
+## From: Getting Started & Tutorials — 1. Installation for agents
+
+Give your AI tooling the Memorix docs as a package before anything else:
+
+```bash
+npm i -D @x12i/memorix-docs
+```
+
+### Why install it
+
+- **Versioned product truth for agents.** Cursor / Codex / CI agents get a pinned, upgradable knowledge surface — no stale prompts, no scraped HTML.
+- **Structured Markdown.** Per-book MD, chapter indexes, use-case packs, and `agent-manifest.json` ship inside the package.
+- **Typed discovery.** `listUseCases`, `getBookMarkdown`, `getUseCaseMarkdown` answer “which book / chapter?” without hallucinated paths.
+- **Knowledge out of prompts.** Product rules (four-field relationships, explicit installs, V2 envelope) live in a dependency you update deliberately.
+
+### The devDependency rule
+
+`@x12i/memorix-docs` documents the product for tools. It is **never** a production runtime dependency:
+
+- Do: `devDependencies`, pin or caret the version, point agent rules/skills at the package.
+- Do not: add to `dependencies`, import from shipped product code, or fork the content.
+
+Humans do not need the package — this website is the human surface.
+
+---
+
+## From: Getting Started & Tutorials — 2. Getting started
+
+Scope first, always:
+
+```http
+x-memorix-org-id: g12ops<suffix>
+x-memorix-agent-ids: ops
+```
+
+Fresh `g12ops*` orgs only — never live customer orgs. Singular `agentId` headers are rejected.
+
+The working loop:
+
+1. **Run the local stack** (chapter 4) — ops-source + memorix-service + Studio.
+2. **Install ops metadata** into your fresh org — `@x12i/memorix-ops-pack` provides agent `ops`, object types, abstracts, relationships, mappings, pipelines, sources, and services in one explicit install.
+3. **Read and write** through `/api/data` only (chapter 5) — no direct Mongo, ever.
+4. **Promote raw via pipelines** (chapter 7) and **materialize links** (chapter 8).
+
+Subjects you will meet everywhere: employee **Alex**, work item **WI-100**, procedure **PROC-2**.
+
+---
+
+## From: Getting Started & Tutorials — 4. Tutorial — run the local stack
+
+Goal: ops-source + memorix-service + Studio on default ports.
+
+```bash
+# from monorepo root
+node scripts/dev-stack.mjs
+```
+
+Open:
+
+- Studio: `http://127.0.0.1:5101/`
+- Stack status: `http://127.0.0.1:5103/`
+- OpenAPI: `http://127.0.0.1:5100/api/openapi.json`
+- Health: `http://127.0.0.1:5100/health` · `http://127.0.0.1:5102/health`
+
+Variants: `--list` prints URLs without starting; `--dev` runs the service in dev mode. Prod mode needs `MONGO_URI`. Ctrl+C stops the stack.
+
+Check:
+
+```bash
+curl -sS http://127.0.0.1:5100/health
+curl -sS http://127.0.0.1:5102/health
+curl -sS http://127.0.0.1:5103/api/status
+```
+
+---
+
+## From: Getting Started & Tutorials — 5. Tutorial — first read and write
+
+Goal: call `/api/data` with correct scope; understand revision preconditions.
+
+Prerequisite: stack running, ops metadata installed for your `g12ops*` org.
+
+Scope every call:
+
+```bash
+ORG=g12ops<suffix>
+AGENTS=ops
+
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  http://127.0.0.1:5100/api/openapi.json | head
+```
+
+Read metadata first — resolve effective object/content types and views so you know legal addresses (paths under `/api/metadata`, see OpenAPI).
+
+Write then read:
+
+1. Create with revision precondition `absent`; update with the exact `revision`.
+2. Get / list / compose the same `recordId`.
+3. On a stale conflict: re-read, re-apply intent, retry.
+
+Do not: omit scope headers, write with the Mongo driver, or invent list columns in your host — drive UI from metadata views.
+
+---
+
+## From: Getting Started & Tutorials — 2. Getting started
+
+Scope bar first, always:
+
+1. Choose a **fresh** `g12ops*` organization — never a live customer org.
+2. Set agent to **`ops`**.
+3. Confirm Design / Operate / Explore show that same scope.
+
+Then the working loop:
+
+1. **Run the local stack** (chapter 4) — or ask engineering for a running Studio.
+2. **Design** — confirm ops metadata is installed (explicit install; nothing auto-installs).
+3. **Operate** — Memory pull, then the promotion pipeline.
+4. **Explore** — confirm composition and links for **WI-100**, **Alex**, **PROC-2**.
+
+If screens look empty or show wrong types: fix scope and metadata install before filing a bug.
+
+---
+
+## From: Getting Started & Tutorials — 4. Tutorial — run the local stack
+
+Goal: a running Studio against the local ops fixture stack.
+
+1. From the monorepo root: `node scripts/dev-stack.mjs` (or ask engineering).
+2. Open Studio at `http://127.0.0.1:5101/`.
+3. Check stack status at `http://127.0.0.1:5103/` — all services healthy.
+4. Set the scope bar: fresh `g12ops*` + agent `ops`.
+
+Ctrl+C stops the stack. Never point drills at live customer orgs.
+
+---
+
+## From: Getting Started & Tutorials — 7. Tutorial — memory to pipeline
+
+Goal: land exact source material, then promote it — the acceptance path.
+
+1. **Operate → Memory** — pull from ops-source; confirm **PROC-2** raw landed (`credentialRef` only).
+2. **Operate → Runs** — start the promotion pipeline; watch runs / attempts.
+3. If a step fails: open the **artifact**, fix metadata/mapping/service, retry from Operate — once, intentionally.
+4. **Explore** — open **WI-100**; confirm snapshot / workflow siblings appeared as designed.
+
+Raw sitting in Memory is not a bug — promotion is always an explicit pipeline path.
+
+---
+
+## Also see
+
+- **Platform Overview** (`00-platform-overview`) — Surfaces, packages, hard rules, and where to start — developers and builders twins.
+- **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-design-types.md

@@ -0,0 +1,122 @@
+# Design object and content types in Studio
+
+> **Use case id:** `studio-design-types`
+> **Goal:** Change product shape in Design without shipping engine code.
+> **Audiences:** builders
+> **Tags:** studio, design, metadata
+
+## Reading path
+
+1. **Workflow & Studio** (builders) → chapters: `1-scope-bar-first-always`, `2-design`
+1. **Metadata, Agents, Abstracts & Mappings** (builders) → chapters: `2-design-screens-you-will-use`, `3-builder-workflow-ops`
+
+## 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 — 2. Design
+
+Author and govern what the platform *can* run:
+
+| Screen family | You do this |
+|---|---|
+| Agents | Inheritance and which vocabulary is in scope |
+| Sources | Where Memory pulls from (e.g. ops-source) |
+| Object / content types | What subjects exist and what content they may wear |
+| Abstracts | Virtual unions (e.g. People) — not separate databases |
+| Relationships | Definitions for navigation links |
+| Mappings / views | Deterministic transforms and list shapes |
+| Services / pipelines / schedules | Capabilities and ordered runs |
+| Intelligence proposals | Review suggested metadata — **never** auto-live |
+| Install / publish | Explicitly make a pack version effective |
+
+Operator rule: proposals are suggestions. You **install** deliberately (see Intelligence builders book).
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 2. Design screens you will use
+
+### Agents and inheritance
+
+![Agents inheritance](../screenshots/02-agents-inheritance.png)
+
+Agents are named vocabularies, not chatbots. Child agents inherit from parents and can override. What your scope actually uses is the **effective** set after inheritance — not a single file you edit blindly.
+
+For acceptance drills, stay on parent **`ops`**.
+
+### Object and content types
+
+![Object & content types](../screenshots/04-object-content-types.png)
+
+Object types are concrete subjects (`employees`, `work-items`, `procedures`, …). Content types are kinds of information about them (`raw`, `snapshots`, `workflow`, …).
+
+Same subject keeps the same id. Different content kinds become siblings (composition). You do not flatten everything into one blob.
+
+### Abstracts and bindings
+
+![Abstracts & bindings](../screenshots/05-abstracts-bindings.png)
+
+An abstract such as **People** is a virtual union of employees and contractors. There is no separate “people database” and no abstract subject id you can invent.
+
+Bindings say which concrete types participate and how abstract fields map onto concrete snapshot fields.
+
+### People union in Explore
+
+![People union](../screenshots/11-people-union.png)
+
+After metadata is installed and subject content exists, Explore can list **People** as one unified view. Writers still always target a concrete type (or an abstract patch that reverse-maps to one concrete writer).
+
+### Explicit install
+
+![Explicit metadata installation](../screenshots/19-explicit-metadata-installation.png)
+
+Intelligence may **propose** metadata. Proposals are not live until you **install / publish** deliberately. Never expect auto-install.
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 3. Builder workflow (ops)
+
+Use this sequence every time you change vocabulary:
+
+1. **Choose agent scope** — `ops` on a fresh `g12ops*` org.
+2. **Define or confirm object/content types** — employees, contractors, work-items, procedures, activity-events.
+3. **Bind abstracts** — People = employees ∪ contractors; remember: virtual only.
+4. **Author mappings** where transforms are deterministic (source fields → raw/snapshot paths, abstract property maps).
+5. **Validate**, then **install / publish** deliberately.
+6. **Prove in Explore** — People list, Alex, WI-100 composition — before you run Memory or pipelines for real work.
+
+```text
+Design vocabulary
+  → validate
+  → explicit install
+  → Explore proves types/abstracts
+  → Operate runs Memory / pipelines / relationships
+```
+
+### Tips while authoring
+
+- Prefer clear titles and identifiers over clever nested payloads.
+- Keep cyber/vendor vocabulary out of the permanent ops narrative.
+- If a proposal looks wrong, **reject it** — do not install “to see what happens” on a shared org.
+- Treat abstract names as views, not storage.
+
+---
+
+## 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/studio-explore-subject.md

@@ -0,0 +1,89 @@
+# Explore a composed subject in Studio
+
+> **Use case id:** `studio-explore-subject`
+> **Goal:** Read composition vs relationships visually in Explore.
+> **Audiences:** builders
+> **Tags:** studio, explore
+
+## Reading path
+
+1. **Workflow & Studio** (builders) → chapters: `4-explore`
+1. **Format for Dummies** (builders) → chapters: `1-what-you-see-in-explore`, `2-composition-vs-relationship`
+
+## From: Workflow & Studio — 4. Explore
+
+![Composed subject](../screenshots/10-composed-subject.png)
+
+Explore is where you inspect **truth about subjects**:
+
+- Concrete records (employees, work-items, procedures, …)
+- Abstract unions (People, …)
+- **Composition** — siblings on the same id (snapshot + workflow + analysis, …)
+- **Relationships** — four-field links between different ids (expansion shows current targets)
+- Workflow / analysis / decisions editors
+
+![Workflow edit](../screenshots/16-workflow-edit.png)
+
+### Composition vs relationship (builder wording)
+
+```text
+Same subject id     → composition (siblings on one page)
+Different subject ids → relationship (link + expansion)
+```
+
+You should never see a pasted “associated employee payload” block inside a work-item snapshot. If you do, that content is wrong — escalate with a screenshot.
+
+---
+
+## From: Format for Dummies — 1. What you see in Explore
+
+### A single content document
+
+![Raw record](../screenshots/09-raw-record.png)
+
+One content document about one subject — for example a work-item snapshot. You can open technical details for JSON, but ordinary review should stay on forms and status.
+
+### Composition (siblings)
+
+![Composed subject](../screenshots/10-composed-subject.png)
+
+Ask Explore for “everything about WI-100” and Studio shows **siblings** — snapshot, workflow, analyses — without flattening them into one blob. Same subject id; different content types.
+
+### Discriminators (many instances)
+
+![Discriminators](../screenshots/12-analysis-decision-discriminators.png)
+
+Some content types allow **many instances** on the same subject (for example several analyses or decisions). A **discriminator** labels which instance you are looking at so saves do not overwrite the wrong sibling.
+
+| Idea | Builder meaning |
+|---|---|
+| One snapshot | Usually one current business picture |
+| Many analyses | Each needs a clear label (discriminator) |
+| Workflow | Process / assignment state — ordinary sibling, not a separate product |
+
+---
+
+## From: Format for Dummies — 2. Composition vs relationship
+
+```text
+Same recordId            → composition (siblings on one Explore page)
+Different recordIds      → relationship (link + expansion)
+```
+
+| Composition | Relationship |
+|---|---|
+| Snapshot + workflow on WI-100 | Alex **assigned to** WI-100 |
+| Same subject id | Two subject ids |
+| Siblings listed together | Four-field link; expansion shows current targets |
+
+Relationships remember *who links to whom* and *why*. They do **not** paste the other record’s fields into this one. If you see a nested “associated employee payload” inside a work-item snapshot, that content is wrong — screenshot and escalate.
+
+---
+
+## Also see
+
+- **Relationships & Memory** (`06-relationships-and-memory`) — Exact Memory ingest and relationship engine links — never associated* payloads on records.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/studio-operate-pipelines.md

@@ -0,0 +1,100 @@
+# Operate pipelines in Studio
+
+> **Use case id:** `studio-operate-pipelines`
+> **Goal:** Run, retry, and inspect pipeline health from Operate.
+> **Audiences:** builders
+> **Tags:** studio, pipelines, operate
+
+## Reading path
+
+1. **Workflow & Studio** (builders) → chapters: `3-operate`
+1. **Building Pipelines** (builders) → chapters: `4-runs-attempts-and-artifacts`, `6-retry-etiquette`, `9-operate-checklist`
+
+## From: Workflow & Studio — 3. Operate
+
+Watch and recover work in flight:
+
+| Need | Go to |
+|---|---|
+| Pipeline / schedule activity | Runs / Attempts / Schedules |
+| Why something failed | Failures + Artifacts |
+| Source landing | Memory |
+| Link health | Relationship verify / rebuild |
+| Intelligence profiling runs | Intelligence runs (still does **not** install) |
+
+Operate is where you prove the path:
+
+```text
+ops-source → Memory (exact raw) → Pipeline → subjects + links → Explore
+```
+
+Do not “fix” a failed step by hand-editing storage. Fix metadata/mapping/service, then retry from Operate.
+
+---
+
+## From: Building Pipelines — 4. Runs, attempts, and artifacts
+
+| Word | Meaning |
+|---|---|
+| **Run** | One execution of a pipeline |
+| **Step** | One box in the design |
+| **Attempt** | One try of a step (retries add attempts) |
+| **Artifact** | Stored proof of large input/output or captured context |
+
+Operate shows status: pending, running, succeeded, failed, partial, cancelled.
+
+**Partial** means some items or branches succeeded — retry only what failed. Do not assume the whole world rolled back.
+
+**Captured context** freezes the exact revisions a step saw. If someone edits WI-100 in Explore later, a retry still uses the captured artifact unless you intentionally start a new run.
+
+---
+
+## From: Building Pipelines — 6. Retry etiquette
+
+1. Read the failure code and artifact context in Operate.
+2. Fix metadata, mapping, service binding, or source issue.
+3. Retry from Operate (failed step or failed batch items).
+4. Confirm input revisions in artifacts after success.
+5. Open Explore — **WI-100**, **Alex**, **PROC-2** — and confirm composition + links.
+
+If the runtime restarted mid-run, resume should **not** redo completed steps. If it does, escalate — that is a platform defect, not something to “fix” by re-scheduling.
+
+### Partial success in plain words
+
+Example: snapshot write for WI-100 succeeded, relationship write failed. Retry the relationship step only. Do not re-pull the whole world unless Memory itself failed.
+
+---
+
+## From: Building Pipelines — 9. Operate checklist
+
+- [ ] Scope: fresh `g12ops*` + `ops`
+- [ ] Pipeline definition valid in Design
+- [ ] Services/mappings referenced by steps exist for this agent
+- [ ] Schedule enabled only when intended; overlapping runs understood
+- [ ] Failures show attempts + artifacts
+- [ ] Retries intentional
+- [ ] Explore confirms subjects and links after success
+- [ ] No secrets visible in artifacts or records
+- [ ] Intelligence proposals reviewed — never assumed installed
+
+### Quick diagnose
+
+| Symptom | Likely cause |
+|---|---|
+| Fails before any step | Invalid definition, missing binding, or missing durable store in prod |
+| Map step fails | Mapping/schema mismatch on raw |
+| Write fails “stale” | Subject edited since capture — re-read or new run |
+| Green run, empty Explore | Missing write step or wrong object/content type |
+| Links missing | Discover without write, or verify/rebuild not run |
+| AI step flaky | Expect recorded adapter for acceptance; check validation artifacts |
+| Duplicate external ticket | Action step missing/broken idempotency — escalate |
+
+---
+
+## 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._