@x12i/memorix-docs 1.0.1 → 1.1.0

package/files/use-cases/four-field-links.md

@@ -0,0 +1,246 @@
+# Link subjects with four-field relationships
+
+> **Use case id:** `four-field-links`
+> **Goal:** Define relationships, expand on read, never store associated* on records.
+> **Audiences:** developers
+> **Tags:** relationships, links
+
+## Reading path
+
+1. **Relationships & Memory** (developers) → chapters: `3-relationships-four-field-links-only`, `5-reads-virtual-expansion`, `9-hard-rules-relationships-memory`
+1. **Runtime Data Client** (developers) → chapters: `8-relationship-reads`, `15-relationship-mutation-boundary`
+
+## From: Relationships & Memory — 3. Relationships — four-field links only
+
+**Trusted writer:** `@x12i/memorix-relationships` only.  
+**Store:** `@x12i/memorix-relationship-store` (Candidate C, org-scoped per data category).
+
+Hard rule **#3**: links remember endpoints and meaning — they never copy target payloads.
+
+### The only stored link shape
+
+```ts
+{
+  relationshipId: string;            // deterministic
+  relationshipDefinitionId: string;  // which definition produced this link
+  fromRecordId: string;
+  toRecordId: string;
+}
+```
+
+Nothing else belongs on the persisted link:
+
+- No nested employee snapshots
+- No job context blobs
+- No revision copies of either side
+- No `associated*` root buckets on subject records
+
+Job context and revisions live in **operational evidence**, captured via data-plane expansion when the engine needs them — never denormalized onto the link.
+
+### Why four fields
+
+Older shapes nested full related records under `associated*`. That duplicated data, mixed navigation with evidence, and made writes unsafe. The new path:
+
+```text
+Same recordId          → composition (siblings)
+Different recordIds    → relationship (four-field link)
+```
+
+### Definition (metadata) vs link (data)
+
+| Layer | Example |
+|---|---|
+| Relationship **definition** (metadata) | `people-assigned-to-work-items` |
+| Materialized **link** (data) | `{ relationshipId, relationshipDefinitionId, fromRecordId: "…Alex…", toRecordId: "wi-100" }` |
+
+Definitions are authored in packs and installed with other metadata. Links are produced by the engine.
+
+Studio Design shows definitions:
+
+![Relationship definition](../screenshots/06-relationship-definition.png)
+
+### Ops definitions (subset)
+
+From `memorix-ops-pack`:
+
+| Id | Meaning |
+|---|---|
+| `people-assigned-to-work-items` | Person assigned to perform a work item |
+| `work-items-use-procedures` | Work item follows reusable procedures |
+| `activity-events-about-work-items` | Activity event reports progress on a work item |
+| `work-items-depend-on-work-items` | Work item depends on another work item |
+| `people-collaborate-with-people` | Two people collaborate (undirected) |
+
+Example definition sketch:
+
+```json
+{
+  "id": "people-assigned-to-work-items",
+  "name": "People assigned to work items",
+  "meaning": "A person (employee or contractor) is assigned to perform a work item",
+  "directionality": "directed",
+  "from": { "abstractType": "People", "property": "assignedWorkItems" },
+  "to": { "abstractType": "WorkItems", "property": "assignedPeople" },
+  "discoveryRules": [
+    {
+      "id": "from-source-assignee",
+      "kind": "source-field",
+      "sourcePath": "assigneeId",
+      "notes": "ops-source work-items.assigneeId resolves across employees and contractors"
+    }
+  ]
+}
+```
+
+Abstract endpoints (`People`, `WorkItems`) compile to concrete binding plans — the engine does not invent Cartesian products.
+
+---
+
+## From: Relationships & Memory — 5. Reads — virtual expansion
+
+`@x12i/memorix-data` can expand relationships **virtually** at read time:
+
+```ts
+// Conceptual read options
+{
+  relationships: {
+    include: true,
+    depth: 1,
+    expandContentTypes: ["snapshots"], // optional projection of targets
+  },
+}
+```
+
+Rules:
+
+- Expansion is **calculated** for the response — it does not paste payloads into stored links.
+- Unresolved targets remain visible as unresolved (Studio shows this clearly).
+- Expanding content types is a read convenience; writers still address concrete content separately.
+
+![Link traversal / expansion](../screenshots/07-link-traversal-expansion.png)
+
+![Unresolved relationship](../screenshots/08-unresolved-relationship.png)
+
+### Composition vs relationship on read
+
+| Same `recordId` | Different `recordId`s |
+|---|---|
+| Composition / siblings | Relationship expansion |
+| `getContent` / compose APIs | `relationships.include` |
+| Snapshot + workflow + analysis on WI-100 | Alex → WI-100 assignment link |
+
+---
+
+## From: Relationships & Memory — 9. Hard rules (relationships & memory)
+
+1. Acceptance orgs are fresh `g12ops*` with `agentIds: ["ops"]`.
+2. Permanent narrative is non-cyber **ops**.
+3. Relationships are **four-field links only** — no `associated*` storage, no copied payloads.
+4. Abstracts stay virtual — relationship definitions may *reference* abstracts; links still store concrete `recordId`s.
+5. Mutations go through the data plane / trusted writers — never direct Mongo domain writes.
+6. Memory secrets via **`credentialRef` only**.
+7. Memory stops at raw — no promote / analysis / relationship discovery inside Memory.
+8. No ad-hoc product link PUT/DELETE (**405**).
+9. Deterministic fixtures only for acceptance — no live AI required.
+
+Full list: [HARD-RULES.md](../../HARD-RULES.md).
+
+---
+
+## From: Runtime Data Client — 8. Relationship reads
+
+Default content reads contain **no** relationships. Expansion is opt-in.
+
+### Capabilities
+
+- Explicit relationship include / `expandRelationships`
+- Forward and inverse traversal as exposed
+- Filter by relationship definition
+- Independent relationship pagination
+- Selected target content types
+- Abstract target projection where supported
+- Depth-one default / hard limits
+- Unresolved targets surfaced (do not invent data)
+- Related-property filter/sort only when bounded
+- Diagnostics when a query would be unbounded
+
+### Virtual wrapper
+
+```json
+{
+  "source": {
+    "format": "memorix-record/2",
+    "recordId": "employee-10",
+    "objectType": "employees",
+    "contentType": "snapshots"
+  },
+  "relationships": {
+    "items": [
+      {
+        "definition": "employee-owns-work-item",
+        "fromRecordId": "employee-10",
+        "toRecordId": "wi-100",
+        "targetStatus": "resolved"
+      }
+    ],
+    "pageInfo": {}
+  }
+}
+```
+
+Clarify:
+
+- Target content is **current at read time**.
+- Target content is **never copied onto the source** as authoritative storage.
+- Updating Alex’s snapshot changes future expansions; the **stored link remains four fields**.
+- Clients **must not** persist the expansion wrapper as the system of record.
+
+### Four-field links only
+
+Authoritative storage is the central relationships collection: definition + endpoints (+ allowed link metadata). No root `associated*`, no copied neighbor payloads, no relationship sibling content as product storage.
+
+### Unresolved targets
+
+If `wi-100` was removed or never landed, expansion may return `targetStatus: "unresolved"`. Treat that as readable state — decide whether to retry later or show a gap in the UI.
+
+### Ops story
+
+Alex owns WI-100. Get Alex’s snapshot with relationship include for `employee-owns-work-item`. You see a four-field link and optionally the current WI-100 target. Patch Alex’s title → link unchanged → next expansion shows the new title on the source and current WI-100 on the target.
+
+---
+
+## From: Runtime Data Client — 15. Relationship mutation boundary
+
+Ordinary clients **cannot** manually create arbitrary relationship links.
+
+| Allowed | Forbidden |
+|---|---|
+| Trigger authorized discover / verify / rebuild when exposed | Product `PUT`/`DELETE` of individual links (`405` on ad-hoc mutation) |
+| Rebuild **one** relationship definition | Assume metadata publish auto-rebuilds all links |
+| Read / expand four-field links | Copied associated payloads |
+| | Relationship sibling writes as authoritative storage |
+| | Root `associated*` writes |
+
+Materialization belongs to `@x12i/memorix-relationships` / pipelines — not to host apps inventing edges.
+
+### Ops story
+
+After Alex and WI-100 snapshots exist, a discover/materialize step creates a four-field `employee-owns-work-item` link. Updating Alex’s title does **not** rewrite the link. Rebuilding that definition refreshes links for that definition only. Metadata install alone does not magically rebuild.
+
+```bash
+# Verify / rebuild — not ad-hoc link CRUD
+curl -sS \
+  -H "x-memorix-org-id: $ORG" \
+  -H "x-memorix-agent-ids: $AGENTS" \
+  "$BASE/api/relationships/..."
+```
+
+---
+
+## 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/http-process-compliance.md

@@ -0,0 +1,225 @@
+# HTTP process compliance (ports / health / live)
+
+> **Use case id:** `http-process-compliance`
+> **Goal:** Wire core-service, ports-manager, and api-live-view for any process that binds HTTP.
+> **Audiences:** developers
+> **Tags:** ports, core-service, http
+
+## Reading path
+
+1. **Building Services** (developers) → chapters: `14-reference`, `6-bind-and-deploy`
+1. **Platform Overview** (developers) → chapters: `7-local-stack-quick-start`
+
+## From: Building Services — 14. Reference
+
+### Role comparison
+
+| Role | Reads external? | Writes external? | Returns draft? | Uses AI? | Direct Memorix mutation? | Idempotency | Persistence owner |
+|---|---|---|---|---|---|---|---|
+| Collect | Yes | No | Raw handoff | No | Via Memory only | Cursor / content hash | Memory + data plane raw |
+| Enrich | Optional | No | Yes | Optional | No — writer step | Key + revision write | Pipeline writer |
+| Resolve | Optional | No | Candidates | Optional | No — relationship engine | Engine keys | Relationship engine |
+| Action | Optional | Yes | Receipt | Optional | Domain write separate | **Mandatory** | External system + ledger |
+| AI job | Via adapter | No | Yes | Yes | No — writer step | Captured input; one write | Pipeline writer |
+
+### Packages
+
+| Package | Use |
+|---|---|
+| `@x12i/memorix-metadata` | `services[]` definitions |
+| `@x12i/memorix-pipeline` | Steps that invoke services |
+| `@x12i/memorix-pipeline-runtime` | Run/attempt/artifact ledger |
+| `@x12i/memorix-mapping` | Prefer before inventing a service |
+| `@x12i/memorix-memory` | Collect / raw landing |
+| `@x12i/memorix-data` | Canonical read/write ports |
+| `@x12i/memorix-service` | HTTP `/api/*` |
+| `@x12i/memorix-ops-pack` | Acceptance fixtures |
+| `@x12i/core-service` | HTTP process compliance (ports, `/health`, `/_live`) |
+| `@x12i/ports-manager` | Org port zones (Memorix **5100–5119**) |
+| `@x12i/api-live-view` | Embeddable live request UI |
+
+### HTTP process compliance (local services)
+
+**Terminology:** TCP/HTTP **ports** (this section) are not Memorix **canonical data ports** (`PortHandler` / `write-record`). Different layers, same English word.
+
+| Audience | Action |
+|---|---|
+| Remote Memorix **client** (calls `/api/*`) | Do **not** install these kits |
+| New HTTP **worker** Memorix (or Studio) will call | **Must** use `@x12i/core-service` |
+| Studio / ops-source / memorix-service | Already compliant |
+
+Any x12i/exellix process that **binds an HTTP port** should use `@x12i/core-service` (pulls in `@x12i/ports-manager` + `@x12i/api-live-view`).
+
+#### Compliance contract
+
+1. Port from the org zone map (`port-map.json`) — env override OK; avoid/quarantine enforced  
+2. `GET /health` → `{ ok, service, … }`  
+3. `/_live` (+ inbound/worker rings) via api-live-view  
+4. `x-correlation-id` on request/response  
+5. Startup banner: origin · health · live · docs  
+
+#### Fastify
+
+```ts
+import Fastify from "fastify";
+import { attachCoreFastify } from "@x12i/core-service/fastify";
+
+const app = Fastify();
+const core = await attachCoreFastify(app, {
+  identity: {
+    id: "@x12i/my-enrich-worker",
+    title: "Ops enrich worker",
+    zoneId: "memorix",
+    portKey: "api",           // even API default in zone
+    portEnv: "MY_WORKER_PORT",
+    docsPath: "/openapi.json",
+  },
+  getHealth: async () => ({ ok: true, service: "@x12i/my-enrich-worker" }),
+});
+
+await app.listen({ port: core.port, host: "127.0.0.1" });
+```
+
+#### Node `http`
+
+```ts
+import http from "node:http";
+import { createCoreNodeHttp, listenAndAnnounce } from "@x12i/core-service";
+
+const core = createCoreNodeHttp({
+  identity: {
+    id: "ops-source",
+    title: "Ops Source",
+    zoneId: "memorix",
+    portKey: "opsSource",
+    portEnv: "OPS_SOURCE_PORT",
+    docsPath: "/openapi.json",
+  },
+});
+// tryHandleCore → /health + /_live; then your routes
+```
+
+#### Ports manager (Memorix zone)
+
+| Default | Port | Env |
+|---|---|---|
+| `service` / `api` | **5100** | `MEMORIX_SERVICE_PORT` |
+| `studio` / `ui` | **5101** | `MEMORIX_STUDIO_PORT` / `VITE_DEV_PORT` |
+| `opsSource` | **5102** | `OPS_SOURCE_PORT` |
+| `statusHub` | **5103** | `STACK_STATUS_PORT` |
+
+Rules: zone **5100–5119** (20 contiguous); **even = API**, **odd = UI**; never bind avoid list (AirPlay **5000/7000**, …); quarantine **5000–5099**. CLI: `npx x12i-ports zone memorix`. Deep reference: package READMEs for `ports-manager`, `core-service`, `api-live-view`.
+
+Prefer `core-service` over wiring `api-live-view` alone. Register the worker’s `ServiceRef.endpoint` to the even API origin the registry will POST to.
+
+### Authoring checklist
+
+- [ ] Decision guide says “service,” not mapping/Memory/relationship/pipeline alone
+- [ ] Metadata has logical I/O + capabilities; no secrets/URLs as identity
+- [ ] `ServiceRef` registered (`serviceId`); prod fails closed without it
+- [ ] Handler is a `PortHandler` on a real `StepKind` (not invented `invoke-service`)
+- [ ] Side effects and idempotency declared
+- [ ] Drafts vs persistence split clear
+- [ ] HTTP workers use `@x12i/core-service` (`/health`, `/_live`, zone port)
+- [ ] Conformance + ops fixture tests green on `g12ops*`
+- [ ] Evidence scan: no secrets in ledgers/artifacts
+
+### Glossary (service terms)
+
+| Term | Meaning |
+|---|---|
+| Service | Named capability with one logical pack definition (`id`) |
+| ServiceRef | Runtime binding (`serviceId` + `kind` + optional endpoint) |
+| Role / capability | Classification on that one model |
+| StepKind / PortHandler | Executable pipeline step surface — dispatch key |
+| Binding | Registry resolve for a `serviceId` (not handler dispatch) |
+| Draft | Proposed content — not yet stored |
+| DataRef | Reference to inline or artifact payload |
+| Credential ref | Pointer to a secret; never the secret |
+| Attempt | One try of a pipeline step that may invoke a service |
+| TCP port / zone | Local bind address from ports-manager — not a data port |
+
+### Next
+
+- [Building Pipelines — Developers](../../08-pipelines/developers/BOOK.md)
+- [Relationships & Memory](../../06-relationships-and-memory/developers/BOOK.md)
+- [Intelligence](../../10-intelligence/developers/BOOK.md)
+- Studio-oriented twin → [Builders](../builders/BOOK.md)
+
+## From: Building Services — 6. Bind and deploy
+
+### Registry
+
+`createServiceRegistry` merges (later wins):
+
+1. environment defaults (`ServiceRef[]`),
+2. effective metadata services (via `servicesFromMetadata` — pack `id` bridged to `serviceId`),
+3. pipeline-local `services[]` on the v2 `PipelineDefinition`.
+
+Pipeline steps may set optional `serviceId`. The registry **resolves identity / endpoint / credentialRef** — it does **not** dispatch to a per-serviceId function. Dispatch remains `stepKind` → `PortHandler`.
+
+`credentialRef` (or `auth.secretRef`) resolves at runtime. Resolved views expose `hasCredential` — never the secret.
+
+### Production versus development
+
+| Production | Development / test |
+|---|---|
+| Required real `PortHandler` for every used `StepKind` | Explicit stub / recorded adapter |
+| Missing `serviceId` binding fails when the step references it | Opt-in only, clearly labeled |
+| Durable ledger + artifact store | May use isolated fixtures |
+| No fake success | Cannot silently become production default |
+
+Startup fails closed when: required binding missing, handler is a silent stub, durable stores missing, `credentialRef` unresolvable for a required operation, or contracts incompatible.
+
+---
+
+## From: Platform Overview — 7. Local stack (quick start)
+
+From the monorepo after workspace install:
+
+```bash
+node scripts/dev-stack.mjs
+# opens browser tabs: stack status, /_live views, Studio
+# use --no-open to skip browser tabs
+```
+
+| Surface | Default URL |
+|---|---|
+| Studio | http://127.0.0.1:5101/ |
+| Stack status | http://127.0.0.1:5103/ (hub — not Studio; links to each `/_live`) |
+| Service live view | http://127.0.0.1:5100/_live (`@x12i/api-live-view` via `@x12i/core-service`) |
+| Service OpenAPI | http://127.0.0.1:5100/api/openapi.json |
+| Service health | http://127.0.0.1:5100/health |
+| Ops-source live / health | http://127.0.0.1:5102/_live · `/health` |
+
+Ports: Memorix zone **5100–5119** (even = API, odd = UI) from [`@x12i/ports-manager`](../../ports-manager/). Avoid **5000/7000** (macOS AirPlay). Quarantine **5000–5099**. How-to for new HTTP workers: [Building Services — HTTP process compliance](../../07-services/developers/BOOK.md#http-process-compliance-local-services). Remote data clients call `/api/*` only — do not install ports kits.
+
+```bash
+curl -sS \
+  -H 'x-memorix-org-id: g12ops-demo' \
+  -H 'x-memorix-agent-ids: ops' \
+  http://127.0.0.1:5100/api/openapi.json
+```
+
+What to install in *your* app:
+
+```bash
+# Default remote host: nothing required for HTTP
+npm install @x12i/memorix-format@^3.0.1   # optional offline validate/migrate
+
+# Trusted platform process only:
+npm install @x12i/memorix-data@^3.0.1 @x12i/memorix-metadata-runtime@^3.0.1
+
+# New HTTP services in x12i/exellix (bind a port):
+npm install @x12i/core-service
+```
+
+---
+
+## Also see
+
+- **Migration & Troubleshooting** (`13-migration-troubleshooting`) — associated* rejection, stale revisions, HTTP failure matrix, escalate packets.
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/files/use-cases/install-metadata-pack.md

@@ -0,0 +1,180 @@
+# Author and install a metadata pack
+
+> **Use case id:** `install-metadata-pack`
+> **Goal:** Shape agents/OT/CT/abstracts and install/publish deliberately — never auto.
+> **Audiences:** developers
+> **Tags:** metadata, install
+
+## Reading path
+
+1. **Metadata, Agents, Abstracts & Mappings** (developers) → chapters: `2-pack-shape-memorix-metadata-1`, `3-agents-and-inheritance`, `9-install-and-publish-never-auto`, `11-hard-rules-for-metadata-authors`
+
+## From: Metadata, Agents, Abstracts & Mappings — 2. Pack shape (`memorix-metadata/1`)
+
+A pack is a declarative document (or folder of JSON fragments assembled into one). Conceptual top-level:
+
+```text
+agents[]
+objectTypes[]
+abstractTypes[]
+abstractBindings[]          # sometimes named bindings
+relationshipDefinitions[]
+mappings[]
+views[]
+writes[]
+pipelines[]
+sources[] / services[] / schedules[] / …
+kindDeclarations[]
+extensions{}                # items keyed by custom kind id
+```
+
+Minimal sketch (ops-flavored):
+
+```json
+{
+  "format": "memorix-metadata/1",
+  "agentId": "ops",
+  "version": "3.0.0-ops-example",
+  "agents": [
+    {
+      "id": "ops",
+      "name": "Operations",
+      "parentId": null
+    }
+  ],
+  "objectTypes": [
+    {
+      "id": "employees",
+      "name": "Employees",
+      "dataCategory": "entity",
+      "contentTypes": [
+        { "id": "raw" },
+        { "id": "snapshots" }
+      ]
+    }
+  ],
+  "abstractTypes": [],
+  "abstractBindings": [],
+  "relationshipDefinitions": [],
+  "mappings": [],
+  "views": [],
+  "writes": [],
+  "kindDeclarations": [],
+  "extensions": {}
+}
+```
+
+**Why this shape:** one agent owns a vocabulary; object types declare concrete subjects; everything else (abstracts, relationships, pipelines) hangs off that vocabulary. Product words live in **tier 2/4** (instance metadata / packs), never hard-coded into tier-1 engines.
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 3. Agents and inheritance
+
+### What an agent is
+
+An agent is a **named metadata scope** — not a chatbot and not a user account. `ops` is the permanent parent agent for the ops journey. Child agents may inherit and override for project-specific packs.
+
+Studio shows inheritance clearly:
+
+![Agents inheritance](../screenshots/02-agents-inheritance.png)
+
+### Ordered `agentIds[]` → effective metadata
+
+The service resolves **effective metadata** from the ordered `agentIds[]` on the request:
+
+```ts
+// Conceptual
+effective = resolveAgents(metadataStore, ["ops" /* , "project-ops", … */]);
+```
+
+Rules of thumb:
+
+1. **Order matters.** Later agents override earlier ones for the same `(kind, id)`.
+2. **Inheritance fills gaps.** A child that does not redefine `employees` still sees the parent’s `employees`.
+3. **Effective ≠ raw.** `GET /api/metadata/raw` shows one agent’s stored items; `GET /api/metadata/effective` shows the resolved set for the whole `agentIds[]` list.
+4. **Scope is orthogonal to data.** `orgId` selects the data universe; `agentIds[]` selects vocabulary. Same org can be queried with different agent sets.
+
+### Ops parent agent
+
+From `memorix-ops-pack`:
+
+```json
+{
+  "id": "ops",
+  "name": "Operations (generic parent)",
+  "description": "Complete generic parent agent for ordinary operational work. Permanent Memorix acceptance pack.",
+  "parentAgentId": null
+}
+```
+
+Acceptance drills use:
+
+| Field | Value |
+|---|---|
+| `orgId` | Fresh `g12ops*` (never a live customer org) |
+| `agentIds` | `["ops"]` |
+
+See [_shared/ops-scenario.md](../../_shared/ops-scenario.md).
+
+---
+
+## 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.
+
+---
+
+## From: Metadata, Agents, Abstracts & Mappings — 11. Hard rules for metadata authors
+
+1. Acceptance orgs are fresh `g12ops*` with `agentIds: ["ops"]` — never live customer orgs.
+2. Permanent narrative is non-cyber **ops** (employees, work-items, procedures).
+3. Abstracts are virtual only — no abstract collections / abstract `recordId`.
+4. Object types live in agent metadata, not in format.
+5. Custom kinds store/resolve only — engines do not execute them.
+6. Install/publish is explicit — intelligence never auto-installs.
+7. Mutations of subject data go through the data plane — never direct Mongo domain writes.
+8. Deterministic fixtures only for acceptance — no live AI required.
+
+Full list: [HARD-RULES.md](../../HARD-RULES.md).
+
+---
+
+## Also see
+
+- **Agent Packs & Ops** (`11-agent-packs-and-ops`) — Pack layout, harness, g12ops* acceptance, custom kinds, golden V2 validation.
+- **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._