docs(data-modeling): import `mapping` has no guide at all, and `objectExtensions` is documented only inside the protocol spec

[os-elon]

Part of #10206

The gap

mapping is a full metadata kind (MetadataTypeSchema, MappingSchema, defineStack({ mappings }), describe string 'Data Import/Export Mappings'). It was promoted to a kind under the ADR-0088 admission test specifically because a consumer landed: POST /data/:object/import takes a mappingName (#2611), and it is runtime-creatable so the import wizard can save one. Documentation: references/shared/mapping.mdx (83 lines) and nothing else. Grep across the hand-written docs for mappingName returns zero hits — the parameter that makes the kind worth having is undocumented.

objectExtensions lets a package extend an object owned by another package (ObjectExtensionSchema, describe string 'Extensions to objects owned by other packages'). The only prose in the docs tree is an example at content/docs/protocol/objectql/schema.mdx L683–L687 — the protocol spec, which is written for implementers. A developer building on top of someone else's package has no page in data-modeling/ telling them this exists.

File surface

• content/docs/data-modeling/import-mappings.mdx — new
• content/docs/data-modeling/object-extensions.mdx — new
• content/docs/data-modeling/index.mdx — edit (Cards + overview prose)
• content/docs/data-modeling/meta.json — two added entries

⛔ Nothing outside content/docs/data-modeling/. Do not edit protocol/objectql/schema.mdx — cross-link to it; the protocol spec is normative text with its own audience and its own change discipline.

What to write

import-mappings.mdx

From MappingSchema and the real import route:

• what a mapping is, and the two ways one comes into being — shipped in a package via defineStack({ mappings }), or saved at runtime by the import wizard;
• the field-mapping shape itself: source column → target field, and whatever transformation/coercion the schema actually declares (check import-coercion.ts in packages/spec/src/data/ for what the platform really does, and do not promise more);
• the consumer: POST /data/:object/import with mappingName. Show the request. This is the half that is missing today and the reason the page exists;
• what happens on a row that does not match — verify against the implementation rather than assuming.

object-extensions.mdx

From ObjectExtensionSchema and the objectExtensions stack collection:

• when you reach for it — extending an object your package does not own, versus defining your own object;
• what an extension may add and what it may not;
• how it interacts with the customization overlay system (supportsOverlay / the platform-vs-org overlay layers) if it does — verify, do not infer from the name;
• namespace/prefix rules for added fields, if any apply (namespace-prefix.ts in packages/spec/src/kernel/);
• a worked example, and a pointer to protocol/objectql/schema.mdx for the normative text.

⛔ Non-goals

• Do not touch packages/spec/**.
• Do not restate the generated property tables from references/**; link them.
• If either schema turns out to declare properties nothing enforces, that is an ADR-0049 enforce-or-remove finding for the domain:spec seat — report it, do not document it as if it worked.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff.

Acceptance

• A developer importing a CSV into an object can find the mapping page from the Data Modeling sidebar and issue a working mappingName import.
• A developer extending another package's object lands on a page in Data Modeling, not in the protocol spec.
• Named gates green.

[os-elon]

Claim: PM loop round 2 (epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10213-mappings-object-extensions
Worktree: objectstack-issue-10213
Domain: domain:devx
File surface: content/docs/data-modeling/import-mappings.mdx (new), object-extensions.mdx (new), index.mdx, meta.json, plus .claude/workflows/docs-accuracy-audit.js (the --write regeneration — declared, see below) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived mandate (dispatch-gates.mjs --tier over the surface: "the surface hits none of the 1 declared glob(s)"), tier is this seat's call.
Clause-②: no — documentation only.
Serial constraints cleared: content/docs/data-modeling/** — no in-flight claim, no open PR. Round-1 siblings #10209 (root nav), #10210 (ui/**) and #10211 (automation/**) are disjoint. Batch-2 siblings #10215 (api/**) and #10216 (permissions/**) are dispatched alongside and are disjoint by section. ⚠️ All three batch-2 cards WILL each touch .claude/workflows/docs-accuracy-audit.js — the generator appends each card's own lines, so a conflict there is possible if two land close together; whichever lands second re-runs --write on the merged base rather than resolving by hand.

Governed-surface note: the --write regeneration puts .claude/** in this PR's path surface, so the PR is human-merge-only (#9866). Expected, not a deviation to avoid — open the draft PR normally and do not flip it ready.

---

Generated by Claude Code