diff --git a/CHANGELOG.md b/CHANGELOG.md
index c454d71..fa9411d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,28 @@
 
 All notable changes to `content-model-simulator` are documented here.
 
+## [0.6.0] — 2026-05-10
+
+### Added
+- **`cms-sim pull-sanity`** — new CLI subcommand that converts a Sanity dataset NDJSON export (produced by `sanity dataset export`) into the same on-disk shape that `cms-sim pull` produces for Contentful spaces: `contentful-space.json` + `schemas/<type>.js` (one per Sanity `_type`) + `data/entries.ndjson`. The output drops into `cms-sim simulate`, `cms-sim to-import`, and `cms-sim diff` unchanged. Flags: `--input` (required), `--output` (default `./sanity-export`), `--default-locale` (default `en-US`), `--include-drafts`, `--include-assets`, `--source`, `--verbose`. Zero new runtime dependencies. Output contract validated end-to-end; field-type inference (Symbol/Text/Integer/Number/Boolean/Date/Object/RichText/Link/Array) shipped. Pipeline warnings against a real Sanity dataset (link-vehicles export, 21 documents) drop from 97 (`FIELD_NOT_IN_DEFINITION` at baseline) to 0.
+- **`pullSanity(options)`** — programmatic API behind the CLI, exported from `src/sanity/pull-sanity.ts`. Returns `{ schemas, documents, assets, warnings, output }`. Reuses `parseSanity` / `parseSanityString` from the existing `sanity-reader` module.
+- **`inferSchemas(samplesByType, options)`** — pure schema-inference API in `src/sanity/sanity-schema-inference.ts`. Walks document samples per content type, classifies each field's value shape, and emits a `ContentTypeDefinition` plus a `warnings[]` array describing type conflicts and array-collapse fallbacks. Mappings: short strings → `Symbol`, strings >256 chars → `Text`, ISO 8601 → `Date`, integers → `Integer`, floats → `Number`, booleans → `Boolean`, `{_type: reference, _ref}` → `Link Entry`, `{_type: image, asset}` → `Link Asset`, arrays of refs/images/symbols → `Array<Link Entry>` / `Array<Link Asset>` / `Array<Symbol>`. Mixed-shape arrays collapse to `Object` with a warning. Required flag is set when the field is present and non-null in 100% of samples (configurable via `requiredThreshold`).
+- **11 unit tests** for `pullSanity` covering the M1 output contract (three pieces written, `contentful-space.json` shape, custom default locale, one schema per type, Contentful schema shape with inferred fields, camelCase humanization in schema names, entries.ndjson per-line shape, draft/system filtering opt-in via flags, in-memory return shape, empty-input no-write behavior, missing-input error).
+- **18 unit tests** for `inferSchemas` covering primitive shape detection (Symbol/Text by string length, Integer/Number split, Boolean, Date for ISO strings), Sanity-specific shapes (`reference`, `image`, arrays of each), disagreement resolution (majority shape wins with warning, mixed arrays collapse to Object), the `required` flag (100% presence → required; missing or null in any sample → not required), and multi-type orchestration (one schema per type, sorted by id, humanized).
+- **`mapDocumentRefs(docs)`** — pure transform in `src/sanity/sanity-ref-mapper.ts` that rewrites every `{_type: 'reference', _ref}` shape (including nested in arrays/objects, with or without `_key`/`_weak` modifiers) to the Contentful Entry-link shape `{sys: {type: 'Link', linkType: 'Entry', id}}`. Returns the transformed documents plus a `linkTargets` map (`contentTypeId.fieldId` → Set of target content types) harvested from the actual cross-document refs. Image references (`{_type: 'image', asset: {_ref}}`) are left untouched here — M6 handles asset links. `pullSanity` runs `mapDocumentRefs` before writing `entries.ndjson` so the simulator's link-resolution stage populates `linkedEntryIds` and the model graph draws relationship arrows from data, not just schema validations.
+- **`linkContentType` validation inference** in `inferSchemas` — when `linkTargets` is passed, single Link Entry fields get `validations: [{ linkContentType: [...sorted targets] }]` and Array<Link Entry> fields get the same on `items.validations`. Orphan refs (target id missing from dataset) don't pollute the validation list.
+- **15 unit tests** for `mapRefsToContentful` / `mapDocumentRefs` and **6 unit tests** for the linkContentType inference in `pullSanity` covering single + array refs, aggregation across multiple target types, orphan-ref handling, and end-to-end ref rewriting in `entries.ndjson`.
+- **`portableTextToRichText(blocks)`** — converts an array of Sanity Portable Text blocks into a Contentful RichText document (the structured `nodeType` tree, not HTML). Maps block styles (`normal`/`h1..h6`/`blockquote`), groups consecutive `listItem` blocks into `unordered-list` / `ordered-list` with nested `list-item` + `paragraph`, converts span marks (`strong`→`bold`, `em`→`italic`, `underline`, `code`), and wraps spans in `hyperlink` nodes when their mark refs a `link` markDef with `href`. Unknown block styles, marks, annotations, and nested list levels (>1) emit explicit warnings while preserving the underlying text. Custom (non-`block`) PT items are skipped with a warning. Exported from the public API along with `isPortableText`.
+- **`portableText: 'html' | 'richtext' | 'raw'`** option on `SanityReadOptions` (default `'html'` for back-compat). `'richtext'` invokes `portableTextToRichText`; `'raw'` leaves PT blocks untouched. `pullSanity` opts into `'richtext'` so its `entries.ndjson` carries Contentful-shaped RichText documents, which (a) lets `to-import` emit valid RichText payloads for top-level PT fields, and (b) makes `inferSchemas` classify those fields as `RichText` instead of `Object`. The default-`html` path keeps `cms-sim simulate --input=*.ndjson` (Sanity NDJSON detected via `isSanityNDJSON`) and existing transforms producing HTML strings as they did before.
+- **`RichText` shape detection** in `inferSchemas` — objects with `nodeType === 'document'` and an array `content` are classified as `RichText` fields. Verified end-to-end against the link-vehicles Sanity export: `post.body[en]` now lands as a real RichText document with 15 structured content nodes instead of an HTML blob.
+- **18 unit tests** for `portableTextToRichText` covering paragraph / heading / blockquote mapping, decorator marks, hyperlink annotations, list grouping (bullet+number), nested-list flattening warning, unknown-mark/annotation/block-style fallbacks, and non-block skip behavior. **`isPortableText`** has its own 2-test block.
+- **Sanity asset linking** in `pullSanity` (`src/sanity/sanity-asset-mapper.ts`). Image references (`{_type: 'image', asset: {_ref}}`, including those nested in arrays/objects) are rewritten to the canonical Contentful Link/Asset sys shape `{sys: {type: 'Link', linkType: 'Asset', id: <_ref>}}` — matching the shape that `pull` (Contentful) emits for asset-field entries. The asset id is preserved verbatim from `_ref`, so it joins the asset metadata written to `<output>/assets/assets.json` (mirroring pull-contentful's `assets/assets.json` shape: `{id, title, fileName, contentType, url, size}`). End-to-end against the link-vehicles dataset: `ASSET_FIELD_NOT_LINKED` warnings dropped from 13 → 0, `linkedAssetIds` is now populated on every post entry (the model graph picks up entry↔asset relationships), and `mainImage` resolves to a Link/Asset sys instead of a raw `{_type: 'image'}` object. Orphan references (asset id missing from the dataset) are still rewritten — the resulting link is dangling and the simulator's link-resolution stage surfaces it.
+- **11 unit tests** for `buildAssetUrlMap` / `mapImageRefsToLinks` / `mapDocumentAssets` / `toAssetMetadata` covering single + array refs, deep nesting, orphan refs (still rewritten — dangling, expected), pass-through of primitives and Link Entry sys shapes, no input mutation, and `assets.json` shape (including the extension-derived filename fallback when `originalFilename` is empty).
+- **Multi-locale detection + expansion** in `pullSanity` (`src/sanity/sanity-locale-expander.ts`). `detectLocales` scans every document's `data` for objects whose keys all match the locale-code pattern `^[a-z]{2,3}(-[A-Z]{2})?$` (e.g., `en`, `es`, `en-US`, `pt-BR`) and which have no `_type` / `sys` / `nodeType` keys — so Sanity refs, Link sys, and RichText documents are correctly skipped. `expandDocumentsByLocale` then fans each document out to N documents (one per locale), substituting the locale-specific value for every detected localized field and falling back to the base locale when missing. `inferSchemas` consumes the resulting `localizedFields` map to mark those fields `localized: true` on the inferred schema, and `pullSanity` writes the detected locales (with the user's `--default-locale` preserved as base when present) into `contentful-space.json`. The detection logic is per (content type, field) so the same field name can be localized in one CT and not in another.
+- **Inference recognizes Contentful Link sys shapes post-mapping.** The shape detector in `inferSchemas` now classifies `{sys: {type: 'Link', linkType: 'Entry'}}` as `Link Entry` and `{sys: {type: 'Link', linkType: 'Asset'}}` as `Link Asset`, in addition to the original Sanity `{_type: 'reference'}` and `{_type: 'image'}` shapes. This lets `pullSanity` map refs / assets BEFORE inference (so locale expansion sees Contentful-shaped values) without losing the ability to detect Link fields. Required to keep the `linkContentType` validation derivation working after M7's pipeline reorder.
+- **End-to-end on the link-vehicles export:** `contentful-space.json` now reports `baseLocale: 'en', locales: ['en', 'es']`. Each Sanity doc fans out to 2 entry-locale documents (21 → 42). `post.body` is typed `RichText, localized: true` (was `Object`), `post.title` is `Symbol, localized: true` (was `Object`), `post.subtitle` is `Symbol, localized: true`. The simulator merges the 42 documents into 21 entries with 2 locales each, and the pipeline reports `0 warnings, 0 errors` against this dataset — full close-out from the M2 baseline of 97 warnings.
+- **15 unit tests** for `detectLocales` / `expandDocumentsByLocale` covering positive cases (en/es, regional codes, singleton, aggregation across docs), negative cases (refs, Link sys, RichText, arbitrary keys, empty objects), per-CT-per-field scoping, base-locale fallback when a locale value is missing, the no-locale no-op pass-through, and absence of input mutation.
+
 ## [0.5.0] — 2026-05-06
 
 ### Fixed
diff --git a/README.md b/README.md
index 989877c..02c1214 100644
--- a/README.md
+++ b/README.md
@@ -95,6 +95,7 @@ Interactive SVG diagram of your content types and their relationships. Zoom, pan
 | **Offline simulation** | 10-step pipeline: load → validate → transform → link → resolve → convert → merge → validate → stats → report. Zero network calls. |
 | **Contentful validation** | Catches missing required fields, unknown fields, unresolved links, field type mismatches — the same errors Contentful would reject. |
 | **Pull from Contentful** | `cms-sim pull` downloads your existing content model and entries (read-only CDA token). Add `--management-token` to include all field validations. Modify locally, simulate, then apply when ready. |
+| **Pull from Sanity** | `cms-sim pull-sanity` converts a Sanity NDJSON export (`sanity dataset export`) into the same on-disk shape as `cms-sim pull`. Schema inference, `_ref` → Link Entry, image refs → Link Asset, Portable Text → RichText, and locale-shape `{en, es}` fan-out are all handled automatically. Offline, zero deps. |
 | **Mock data generator** | No data? No problem. Auto-generates realistic entries from your schemas with field-type-aware values and cross-references. |
 | **CMS migration preview** | Feed WordPress XML, Sanity NDJSON, or generic JSON exports alongside your Contentful schemas. See exactly how the migrated content will look. |
 | **CI/CD validation** | `cms-sim validate --json` for pipelines. Exit code 1 on errors. |
@@ -147,6 +148,32 @@ npx cms-sim --schemas=schemas/ --input=data/export.ndjson --transforms=transform
 npx cms-sim scaffold --input=data/export.xml --output=my-project/
 ```
 
+#### `cms-sim pull-sanity` — zero-config Sanity → Contentful
+
+When you don't want to hand-write `transforms/`, `pull-sanity` converts a Sanity dataset NDJSON export (the file `sanity dataset export` produces) into the same on-disk shape that `cms-sim pull` writes for a real Contentful space — `contentful-space.json` + `schemas/<type>.js` + `data/entries.ndjson` + `assets/assets.json` — in one command:
+
+```bash
+# Generate the NDJSON from your Sanity project (their CLI, not ours)
+sanity dataset export production export.ndjson
+
+# Convert it to Contentful shape (offline, zero deps, read-only)
+npx cms-sim pull-sanity --input=export.ndjson --output=pulled-sanity/
+
+# Now everything downstream works the same as with cms-sim pull
+npx cms-sim --schemas=pulled-sanity/schemas/ --input=pulled-sanity/data/entries.ndjson --open
+npx cms-sim to-import --input=output/ --schemas=pulled-sanity/schemas/ --output=bundle/
+```
+
+What it handles automatically:
+
+- **Schema inference** from real document samples — Symbol / Text / Integer / Number / Boolean / Date / Object / RichText / Link Entry / Link Asset / Array variants. Disagreement between samples picks the dominant shape and emits a warning.
+- **`_ref` → Link Entry** rewrites for both top-level and nested arrays, plus `linkContentType` validations derived from the cross-document refs actually present in the corpus.
+- **Image refs → Link Asset** alongside a generated `assets/assets.json` index (id, title, fileName, contentType, url, size).
+- **Portable Text → Contentful RichText** (paragraph / heading / lists / blockquote / decorators / hyperlinks). Unknown marks, custom block types, and nested list levels emit explicit warnings while preserving the underlying text.
+- **Locale detection** (`{en, es}`, `{en-US, pt-BR}`, …). Each Sanity doc fans out to one document per detected locale; the matching schema fields are marked `localized: true`. `contentful-space.json` reflects the detected locales.
+
+The example at [`example-sanity-pull/`](../example-sanity-pull/) is a runnable walk-through against the link-vehicles dataset.
+
 ### 4. `contentful-migration` preview (`from-migrations`)
 
 You already have migration scripts as your source of truth. Replay them against a mock and see the resulting model — without running them against a real Contentful environment.
diff --git a/package-lock.json b/package-lock.json
index 9bab03a..95c385d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "content-model-simulator",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "content-model-simulator",
-      "version": "0.3.0",
+      "version": "0.6.0",
       "license": "MIT",
       "bin": {
         "cms-sim": "bin/cms-sim.js"
diff --git a/package.json b/package.json
index 739d065..8a55f37 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "content-model-simulator",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local-only simulator for Contentful content models. Preview entries, validate schemas, and export ready-to-import bundles — without connecting to Contentful.",
   "type": "module",
   "main": "dist/index.js",
diff --git a/src/cli.ts b/src/cli.ts
index 5129043..477b024 100755
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -4,6 +4,7 @@
  * Usage:
  *   cms-sim --schemas <dir> [options]        Simulate locally
  *   cms-sim pull --space-id=XXX [options]    Download from Contentful
+ *   cms-sim pull-sanity --input=<file> [opt] Convert a Sanity NDJSON export to the same shape as `pull`
  *   cms-sim --help
  */
 
@@ -182,6 +183,7 @@ ${c.cyan}COMMANDS:${c.reset}
   cms-sim scaffold [options]     ${c.dim}Generate schemas + transforms from a WordPress XML export${c.reset}
   cms-sim from-migrations [opts] ${c.dim}Convert contentful-migration scripts → cms-sim schemas${c.reset}
   cms-sim pull [options]         ${c.dim}Download content model from Contentful${c.reset}
+  cms-sim pull-sanity [options]  ${c.dim}Convert a Sanity NDJSON export to the same shape as ${c.bold}pull${c.reset}${c.dim} (offline)${c.reset}
   cms-sim diff --old=A --new=B   ${c.dim}Compare two schema directories${c.reset}
   cms-sim validate [options]     ${c.dim}Validate schemas + data (no HTML output)${c.reset}
 
@@ -915,6 +917,150 @@ async function pullMain(argv: string[]): Promise<void> {
   console.log('');
 }
 
+// ── pull-sanity sub-command ──────────────────────────────────────
+
+function showPullSanityHelp(): void {
+  console.log(`
+${c.bold}Content Model Simulator — Pull Sanity${c.reset}
+Convert a Sanity dataset NDJSON export into the same on-disk shape that
+${c.bold}cms-sim pull${c.reset} produces (Contentful-flavored). The result drops into
+${c.bold}cms-sim simulate${c.reset}, ${c.bold}cms-sim to-import${c.reset}, and ${c.bold}cms-sim diff${c.reset} unchanged.
+
+${c.cyan}USAGE:${c.reset}
+  cms-sim pull-sanity --input=<file> [options]
+
+${c.cyan}REQUIRED:${c.reset}
+  --input=<file>          Path to the Sanity NDJSON export (produced by ${c.bold}sanity dataset export${c.reset})
+
+${c.cyan}OPTIONS:${c.reset}
+  --output=<dir>          Output directory (default: ./sanity-export)
+  --default-locale=<code> Locale tag assigned to every entry (default: en-US)
+  --include-drafts        Include documents whose _id starts with ${c.bold}drafts.${c.reset} (default: off)
+  --include-assets        Emit ${c.bold}sanity.imageAsset${c.reset} docs as entries too (default: kept separately)
+  --source=<label>        Label written to contentful-space.json (default: --input value)
+  --verbose, -v           Print progress
+  --help, -h              Show this help
+
+${c.cyan}OUTPUT (mirrors ${c.bold}cms-sim pull${c.reset}):${c.reset}
+  <output>/
+    schemas/              ${c.dim}One .js per Sanity _type, with fields inferred from real documents${c.reset}
+    contentful-space.json ${c.dim}{ baseLocale, locales[], pulledAt, source, sourceFormat: 'sanity-ndjson' }${c.reset}
+    data/entries.ndjson   ${c.dim}One JSON per line — { contentType, id, locale, path?, data }${c.reset}
+
+${c.cyan}EXAMPLES:${c.reset}
+  ${c.dim}# Generate an NDJSON export from Sanity, then pull it into cms-sim shape${c.reset}
+  sanity dataset export production export.ndjson
+  cms-sim pull-sanity --input=export.ndjson --output=pulled-sanity/
+
+  ${c.dim}# Simulate using the pulled output, same as with Contentful pull${c.reset}
+  cms-sim --schemas=pulled-sanity/schemas/ --input=pulled-sanity/data/entries.ndjson --open
+
+${c.yellow}Status (v0.6.0 in progress):${c.reset} M1 (output contract) and M2 (schema inference) shipped.
+${c.dim}                            Still ahead: M4 refs/edges, M5 Portable Text → RichText,${c.reset}
+${c.dim}                            M6 asset Link resolution, M7 multi-locale detection.${c.reset}
+`);
+}
+
+interface PullSanityArgs {
+  input: string | null;
+  output: string;
+  defaultLocale: string;
+  includeDrafts: boolean;
+  includeAssets: boolean;
+  source: string | null;
+  verbose: boolean;
+  help: boolean;
+}
+
+async function pullSanityMain(argv: string[]): Promise<void> {
+  const args: PullSanityArgs = {
+    input: null,
+    output: './sanity-export',
+    defaultLocale: 'en-US',
+    includeDrafts: false,
+    includeAssets: false,
+    source: null,
+    verbose: false,
+    help: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') { args.help = true; continue; }
+    if (arg === '--verbose' || arg === '-v') { args.verbose = true; continue; }
+    if (arg === '--include-drafts') { args.includeDrafts = true; continue; }
+    if (arg === '--include-assets') { args.includeAssets = true; continue; }
+
+    const eq = arg.indexOf('=');
+    if (eq === -1) continue;
+    const key = arg.startsWith('--') ? arg.substring(2, eq) : arg.substring(0, eq);
+    const val = arg.substring(eq + 1);
+
+    switch (key) {
+      case 'input': args.input = val; break;
+      case 'output': args.output = val; break;
+      case 'default-locale': args.defaultLocale = val; break;
+      case 'source': args.source = val; break;
+    }
+  }
+
+  if (args.help) { showPullSanityHelp(); process.exit(0); }
+
+  if (!args.input) {
+    console.error(`${c.red}Error:${c.reset} --input=<file> is required (path to a Sanity NDJSON export).`);
+    console.error(`Run ${c.bold}cms-sim pull-sanity --help${c.reset} for usage.`);
+    process.exit(1);
+  }
+
+  const inputPath = resolve(args.input);
+  if (!existsSync(inputPath)) {
+    console.error(`${c.red}Error:${c.reset} Input file not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  const outputDir = resolve(args.output);
+
+  console.log(`\n${c.cyan}${'═'.repeat(68)}${c.reset}`);
+  console.log(`${c.bold}Content Model Simulator — Pull Sanity${c.reset}`);
+  console.log(`${c.cyan}${'═'.repeat(68)}${c.reset}\n`);
+  console.log(`${c.dim}Reading Sanity NDJSON export (offline)…${c.reset}\n`);
+
+  const { pullSanity } = await import('./sanity/pull-sanity.js');
+
+  const result = await pullSanity({
+    input: inputPath,
+    output: outputDir,
+    defaultLocale: args.defaultLocale,
+    includeDrafts: args.includeDrafts,
+    includeAssets: args.includeAssets,
+    source: args.source || undefined,
+    verbose: args.verbose,
+  });
+
+  console.log(`${c.green}✓${c.reset} ${c.bold}${result.schemas.length}${c.reset} content type(s) detected`);
+  console.log(`${c.green}✓${c.reset} ${c.bold}${result.documents.length}${c.reset} entry/entries written`);
+  console.log(`${c.green}✓${c.reset} ${c.bold}${result.assets.length}${c.reset} asset(s) detected (kept in memory; not downloaded yet)`);
+
+  console.log(`\n${c.cyan}${'─'.repeat(68)}${c.reset}`);
+  console.log(`${c.bold}Output:${c.reset} ${outputDir}`);
+  console.log(`${c.dim}  schemas/              → ${result.schemas.length} content type definitions (fields inferred from samples)${c.reset}`);
+  if (result.warnings.length > 0) {
+    console.log(`${c.yellow}  ⚠ ${result.warnings.length} inference warning(s)${c.reset}${c.dim} — re-run with --verbose to see them${c.reset}`);
+  }
+  console.log(`${c.dim}  contentful-space.json  → locale + source metadata${c.reset}`);
+  if (result.documents.length > 0) {
+    console.log(`${c.dim}  data/entries.ndjson   → ${result.documents.length} entry-locale documents${c.reset}`);
+  }
+
+  console.log(`\n${c.cyan}Next steps:${c.reset}`);
+  const outBase = args.output.replace(/\/+$/, '');
+  if (result.documents.length > 0) {
+    console.log(`  cms-sim --schemas=${outBase}/schemas/ --input=${outBase}/data/entries.ndjson --open`);
+  } else {
+    console.log(`  cms-sim --schemas=${outBase}/schemas/ --open`);
+  }
+  console.log('');
+}
+
 // ── Diff sub-command ─────────────────────────────────────────────
 async function diffMain(argv: string[]): Promise<void> {
   let oldDir: string | null = null, newDir: string | null = null, help = false, jsonOut = false;
@@ -1821,6 +1967,7 @@ ${c.cyan}Next steps:${c.reset}
 // ── Entry point ──────────────────────────────────────────────────
 const rawArgs = process.argv.slice(2);
 const subCommand = rawArgs[0] === 'pull' ? 'pull'
+  : rawArgs[0] === 'pull-sanity' ? 'pull-sanity'
   : rawArgs[0] === 'diff' ? 'diff'
   : rawArgs[0] === 'validate' ? 'validate'
   : rawArgs[0] === 'init' ? 'init'
@@ -1835,6 +1982,12 @@ if (subCommand === 'pull') {
     if (process.env.DEBUG) console.error(err.stack);
     process.exit(1);
   });
+} else if (subCommand === 'pull-sanity') {
+  pullSanityMain(rawArgs.slice(1)).catch(err => {
+    console.error(`${c.red}${c.bold}Fatal error:${c.reset} ${err.message}`);
+    if (process.env.DEBUG) console.error(err.stack);
+    process.exit(1);
+  });
 } else if (subCommand === 'diff') {
   diffMain(rawArgs.slice(1)).catch(err => {
     console.error(`${c.red}${c.bold}Fatal error:${c.reset} ${err.message}`);
diff --git a/src/index.ts b/src/index.ts
index b196e86..b463f2b 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -113,3 +113,15 @@ export type { ScaffoldAnalysis, AnalyzedContentType, AnalyzedField, ScaffoldOpti
 // ── Sanity ───────────────────────────────────────────────────────
 export { readSanity, parseSanity, parseSanityString, portableTextToHTML, isSanityNDJSON } from './sanity/sanity-reader.js';
 export type { SanityReadOptions, SanityImageAsset, SanityResult } from './sanity/sanity-reader.js';
+export { portableTextToRichText, isPortableText } from './sanity/portable-text-to-richtext.js';
+export type { RichTextWarning, RichTextResult } from './sanity/portable-text-to-richtext.js';
+export { pullSanity } from './sanity/pull-sanity.js';
+export type { PullSanityOptions, PullSanityResult } from './sanity/pull-sanity.js';
+export { inferSchemas as inferSanitySchemas } from './sanity/sanity-schema-inference.js';
+export type { InferenceWarning as SanityInferenceWarning, InferenceResult as SanityInferenceResult, InferenceOptions as SanityInferenceOptions } from './sanity/sanity-schema-inference.js';
+export { mapRefsToContentful, mapDocumentRefs } from './sanity/sanity-ref-mapper.js';
+export type { RefMapResult } from './sanity/sanity-ref-mapper.js';
+export { buildAssetUrlMap, mapImageRefsToLinks, mapDocumentAssets, toAssetMetadata } from './sanity/sanity-asset-mapper.js';
+export type { AssetMapResult, PullSanityAssetMeta } from './sanity/sanity-asset-mapper.js';
+export { detectLocales, expandDocumentsByLocale } from './sanity/sanity-locale-expander.js';
+export type { LocaleDetectionResult, ExpandOptions as LocaleExpandOptions } from './sanity/sanity-locale-expander.js';
diff --git a/src/sanity/portable-text-to-richtext.test.ts b/src/sanity/portable-text-to-richtext.test.ts
new file mode 100644
index 0000000..22355d9
--- /dev/null
+++ b/src/sanity/portable-text-to-richtext.test.ts
@@ -0,0 +1,223 @@
+/**
+ * Tests for src/sanity/portable-text-to-richtext.js — v0.6.0 M5.
+ *
+ * Verifies each Portable Text → Contentful RichText mapping rule:
+ * paragraph, headings, lists (bullet/number, consecutive grouping),
+ * blockquote, decorator marks (bold/italic/underline/code), hyperlink
+ * annotations, unknown-mark fallback with warning, non-block skip,
+ * empty input. Also verifies the result is structurally a valid
+ * Contentful RichText document (root `nodeType: 'document'`).
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { portableTextToRichText, isPortableText } from './portable-text-to-richtext.js';
+
+function span(text: string, marks: string[] = []) {
+  return { _type: 'span', _key: `s-${text.slice(0, 4)}`, text, marks };
+}
+
+function block(style: string | undefined, children: ReturnType<typeof span>[], extra: Record<string, unknown> = {}) {
+  return { _type: 'block', _key: `b-${style}`, style, children, markDefs: [], ...extra };
+}
+
+// ── Document shape ───────────────────────────────────────────────
+
+describe('portableTextToRichText — document shape', () => {
+  it('produces a Contentful RichText document at the root', () => {
+    const { document } = portableTextToRichText([block('normal', [span('Hi')])]);
+    assert.equal(document.nodeType, 'document');
+    assert.ok(Array.isArray(document.content));
+    assert.deepEqual(document.data, {});
+  });
+
+  it('returns an empty document for an empty input', () => {
+    const { document, warnings } = portableTextToRichText([]);
+    assert.deepEqual(document, { nodeType: 'document', data: {}, content: [] });
+    assert.deepEqual(warnings, []);
+  });
+});
+
+// ── Block-level mapping ──────────────────────────────────────────
+
+describe('portableTextToRichText — block styles', () => {
+  it('maps `normal` to paragraph', () => {
+    const { document } = portableTextToRichText([block('normal', [span('Hello')])]);
+    assert.equal(document.content[0].nodeType, 'paragraph');
+  });
+
+  it('maps `h1`..`h6` to heading-1..heading-6', () => {
+    for (const level of [1, 2, 3, 4, 5, 6]) {
+      const { document } = portableTextToRichText([block(`h${level}`, [span(`H${level}`)])]);
+      assert.equal(document.content[0].nodeType, `heading-${level}`);
+    }
+  });
+
+  it('maps `blockquote` to blockquote', () => {
+    const { document } = portableTextToRichText([block('blockquote', [span('Quoted')])]);
+    assert.equal(document.content[0].nodeType, 'blockquote');
+  });
+
+  it('warns and falls back to paragraph for unknown block styles', () => {
+    const { document, warnings } = portableTextToRichText([block('h7' as any, [span('weird')])]);
+    assert.equal(document.content[0].nodeType, 'paragraph');
+    assert.ok(warnings.some(w => w.code === 'unknown-block-style'));
+  });
+});
+
+// ── Text + decorator marks ───────────────────────────────────────
+
+describe('portableTextToRichText — span marks', () => {
+  it('wraps text nodes with bold/italic/underline/code marks', () => {
+    const { document } = portableTextToRichText([
+      block('normal', [
+        span('plain'),
+        span('bold', ['strong']),
+        span('italic', ['em']),
+        span('underline', ['underline']),
+        span('code', ['code']),
+      ]),
+    ]);
+    const ps = document.content[0].content!;
+    assert.deepEqual(ps[0].marks, []);
+    assert.deepEqual(ps[1].marks, [{ type: 'bold' }]);
+    assert.deepEqual(ps[2].marks, [{ type: 'italic' }]);
+    assert.deepEqual(ps[3].marks, [{ type: 'underline' }]);
+    assert.deepEqual(ps[4].marks, [{ type: 'code' }]);
+  });
+
+  it('warns and drops unknown marks while preserving text', () => {
+    const { document, warnings } = portableTextToRichText([
+      block('normal', [span('mystery', ['highlight-yellow'])]),
+    ]);
+    const textNode = document.content[0].content![0];
+    assert.equal(textNode.value, 'mystery');
+    assert.deepEqual(textNode.marks, []);
+    assert.ok(warnings.some(w => w.code === 'unknown-mark'));
+  });
+});
+
+// ── Hyperlink annotations ────────────────────────────────────────
+
+describe('portableTextToRichText — annotations', () => {
+  it('wraps a span in a hyperlink node when its mark refs a link markDef', () => {
+    const { document } = portableTextToRichText([
+      {
+        _type: 'block', _key: 'b1', style: 'normal',
+        children: [
+          { _type: 'span', _key: 's1', text: 'Click ', marks: [] },
+          { _type: 'span', _key: 's2', text: 'here', marks: ['link1'] },
+        ],
+        markDefs: [{ _key: 'link1', _type: 'link', href: 'https://example.com' }],
+      },
+    ]);
+    const para = document.content[0];
+    const [, linkNode] = para.content!;
+    assert.equal(linkNode.nodeType, 'hyperlink');
+    assert.deepEqual(linkNode.data, { uri: 'https://example.com' });
+    assert.equal(linkNode.content?.[0].value, 'here');
+  });
+
+  it('warns and unwraps unknown annotations, keeping the text', () => {
+    const { document, warnings } = portableTextToRichText([
+      {
+        _type: 'block', _key: 'b1', style: 'normal',
+        children: [{ _type: 'span', _key: 's1', text: 'Highlighted', marks: ['custom1'] }],
+        markDefs: [{ _key: 'custom1', _type: 'customAnnotation' }],
+      },
+    ]);
+    const textNode = document.content[0].content![0];
+    assert.equal(textNode.nodeType, 'text');
+    assert.equal(textNode.value, 'Highlighted');
+    assert.ok(warnings.some(w => w.code === 'unknown-annotation'));
+  });
+});
+
+// ── Lists ────────────────────────────────────────────────────────
+
+describe('portableTextToRichText — lists', () => {
+  it('groups consecutive bullet items into one unordered-list', () => {
+    const { document } = portableTextToRichText([
+      block('normal', [span('A')], { listItem: 'bullet' }),
+      block('normal', [span('B')], { listItem: 'bullet' }),
+      block('normal', [span('C')], { listItem: 'bullet' }),
+    ]);
+    assert.equal(document.content.length, 1);
+    const ul = document.content[0];
+    assert.equal(ul.nodeType, 'unordered-list');
+    assert.equal(ul.content?.length, 3);
+    assert.equal(ul.content![0].nodeType, 'list-item');
+    // Each list-item wraps a paragraph
+    assert.equal(ul.content![0].content![0].nodeType, 'paragraph');
+  });
+
+  it('separates bullet and number lists into distinct list nodes', () => {
+    const { document } = portableTextToRichText([
+      block('normal', [span('A')], { listItem: 'bullet' }),
+      block('normal', [span('1')], { listItem: 'number' }),
+      block('normal', [span('B')], { listItem: 'bullet' }),
+    ]);
+    assert.equal(document.content.length, 3);
+    assert.equal(document.content[0].nodeType, 'unordered-list');
+    assert.equal(document.content[1].nodeType, 'ordered-list');
+    assert.equal(document.content[2].nodeType, 'unordered-list');
+  });
+
+  it('warns when list items are nested (level > 1) and flattens', () => {
+    const { document, warnings } = portableTextToRichText([
+      block('normal', [span('A')], { listItem: 'bullet', level: 1 }),
+      block('normal', [span('B')], { listItem: 'bullet', level: 2 }),
+    ]);
+    const ul = document.content[0];
+    assert.equal(ul.content?.length, 2);
+    assert.ok(warnings.some(w => w.code === 'nested-list-flattened'));
+  });
+
+  it('returns an empty paragraph (no list items) when listItem style is unknown', () => {
+    const { warnings } = portableTextToRichText([
+      block('normal', [span('A')], { listItem: 'roman' as any }),
+    ]);
+    assert.ok(warnings.some(w => w.code === 'unknown-list-style'));
+  });
+});
+
+// ── Non-block / mixed input ──────────────────────────────────────
+
+describe('portableTextToRichText — non-block items', () => {
+  it('skips non-block items and warns', () => {
+    const { document, warnings } = portableTextToRichText([
+      block('normal', [span('Real block')]),
+      { _type: 'image', asset: { _ref: 'image-abc' } },
+      block('normal', [span('Another')]),
+    ]);
+    assert.equal(document.content.length, 2);
+    assert.ok(warnings.some(w => w.code === 'non-block-skipped'));
+  });
+
+  it('skips null/undefined entries silently', () => {
+    const { document, warnings } = portableTextToRichText([
+      null, undefined,
+      block('normal', [span('Survivor')]),
+    ] as unknown[]);
+    assert.equal(document.content.length, 1);
+    assert.equal(warnings.length, 0);
+  });
+});
+
+// ── isPortableText helper ────────────────────────────────────────
+
+describe('isPortableText', () => {
+  it('detects PT arrays', () => {
+    assert.equal(isPortableText([{ _type: 'block', children: [] }]), true);
+    assert.equal(isPortableText([{ _type: 'block', children: [] }, { _type: 'image' }]), true);
+  });
+
+  it('rejects non-PT arrays', () => {
+    assert.equal(isPortableText([]), false);
+    assert.equal(isPortableText(['plain', 'strings']), false);
+    assert.equal(isPortableText([{ _type: 'image' }]), false);
+    assert.equal(isPortableText('not an array'), false);
+    assert.equal(isPortableText(null), false);
+  });
+});
diff --git a/src/sanity/portable-text-to-richtext.ts b/src/sanity/portable-text-to-richtext.ts
new file mode 100644
index 0000000..7df6b03
--- /dev/null
+++ b/src/sanity/portable-text-to-richtext.ts
@@ -0,0 +1,242 @@
+/**
+ * Content Model Simulator — Portable Text → Contentful RichText (v0.6.0 M5)
+ *
+ * Converts an array of Sanity Portable Text blocks into a Contentful
+ * RichText document (the structured `nodeType` tree, not HTML). The
+ * result is what `contentful-import` expects for a RichText field.
+ *
+ * Mappings (best-effort):
+ * - Block style `normal` → `paragraph`
+ * - Block style `h1`..`h6` → `heading-1`..`heading-6`
+ * - Block style `blockquote` → `blockquote`
+ * - `listItem: 'bullet'` → `unordered-list` of `list-item` (one per block)
+ * - `listItem: 'number'` → `ordered-list` of `list-item`
+ * - Span marks: `strong` → `bold`, `em` → `italic`, `underline` → `underline`,
+ *   `code` → `code`. Unknown marks are dropped and surfaced as warnings.
+ * - markDefs of `_type: 'link'` with `href` → `hyperlink` wrapping the spans
+ *
+ * Limitations (deferred):
+ * - Nested lists (`level > 1`) flatten to level-1 + warning. Contentful
+ *   supports nested lists but the data shape is unambiguous only when the
+ *   Sanity dataset itself uses `level` consistently; many don't.
+ * - Custom block types (e.g., `_type: 'image'` inline blocks, custom
+ *   embeds) skip with a warning rather than guessing `embedded-entry-block`
+ *   — we don't have enough info to resolve the target id reliably.
+ * - Annotations beyond `link` (custom mark defs) drop the annotation and
+ *   keep the underlying text, with a warning.
+ *
+ * Zero-dependency. Pure function (no I/O, no input mutation).
+ */
+
+// ── Public types ─────────────────────────────────────────────────
+
+import type { RichTextNode, RichTextDocument } from '../transform/rich-text.js';
+
+export interface RichTextWarning {
+  code:
+    | 'unknown-block-style'
+    | 'unknown-list-style'
+    | 'unknown-mark'
+    | 'unknown-annotation'
+    | 'nested-list-flattened'
+    | 'non-block-skipped';
+  detail: string;
+}
+
+export interface RichTextResult {
+  document: RichTextDocument;
+  warnings: RichTextWarning[];
+}
+
+// ── Constants ────────────────────────────────────────────────────
+
+const MARK_TO_RICHTEXT: Record<string, string> = {
+  strong: 'bold',
+  em: 'italic',
+  underline: 'underline',
+  code: 'code',
+};
+
+// ── Internal types for the input shape ───────────────────────────
+
+interface PTSpan {
+  _type: 'span' | string;
+  _key?: string;
+  text?: string;
+  marks?: string[];
+}
+
+interface PTMarkDef {
+  _key: string;
+  _type: string;
+  href?: string;
+  [key: string]: unknown;
+}
+
+interface PTBlock {
+  _type: string;
+  _key?: string;
+  style?: string;
+  listItem?: 'bullet' | 'number';
+  level?: number;
+  children?: PTSpan[];
+  markDefs?: PTMarkDef[];
+}
+
+// ── Public API ───────────────────────────────────────────────────
+
+export function portableTextToRichText(blocks: readonly unknown[]): RichTextResult {
+  const warnings: RichTextWarning[] = [];
+  const content: RichTextNode[] = [];
+
+  let i = 0;
+  while (i < blocks.length) {
+    const raw = blocks[i];
+    if (!raw || typeof raw !== 'object') {
+      i++;
+      continue;
+    }
+    const b = raw as PTBlock;
+
+    // Non-block nodes (custom embeds, inline images, etc.) — skip with warning.
+    if (b._type !== 'block') {
+      warnings.push({ code: 'non-block-skipped', detail: `Skipped Portable Text node of type "${b._type}"` });
+      i++;
+      continue;
+    }
+
+    if (b.listItem) {
+      // Group consecutive list items with the same listItem style into one list.
+      const listNodeType = listStyleToNodeType(b.listItem);
+      if (!listNodeType) {
+        warnings.push({ code: 'unknown-list-style', detail: `Unknown listItem style "${b.listItem}"` });
+        i++;
+        continue;
+      }
+      const items: RichTextNode[] = [];
+      while (i < blocks.length) {
+        const next = blocks[i] as PTBlock | null;
+        if (!next || next._type !== 'block' || next.listItem !== b.listItem) break;
+        if ((next.level ?? 1) > 1) {
+          warnings.push({
+            code: 'nested-list-flattened',
+            detail: `Nested list (level ${next.level}) flattened to level 1`,
+          });
+        }
+        items.push({
+          nodeType: 'list-item',
+          data: {},
+          content: [
+            {
+              nodeType: 'paragraph',
+              data: {},
+              content: convertSpans(next.children || [], next.markDefs || [], warnings),
+            },
+          ],
+        });
+        i++;
+      }
+      content.push({ nodeType: listNodeType, data: {}, content: items });
+      continue;
+    }
+
+    // Non-list block.
+    content.push({
+      nodeType: styleToNodeType(b.style, warnings),
+      data: {},
+      content: convertSpans(b.children || [], b.markDefs || [], warnings),
+    });
+    i++;
+  }
+
+  return {
+    document: { nodeType: 'document', data: {}, content },
+    warnings,
+  };
+}
+
+// ── Internals ────────────────────────────────────────────────────
+
+function styleToNodeType(style: string | undefined, warnings: RichTextWarning[]): string {
+  switch (style) {
+    case undefined:
+    case 'normal':
+      return 'paragraph';
+    case 'h1': return 'heading-1';
+    case 'h2': return 'heading-2';
+    case 'h3': return 'heading-3';
+    case 'h4': return 'heading-4';
+    case 'h5': return 'heading-5';
+    case 'h6': return 'heading-6';
+    case 'blockquote': return 'blockquote';
+    default:
+      warnings.push({ code: 'unknown-block-style', detail: `Unknown block style "${style}" mapped to paragraph` });
+      return 'paragraph';
+  }
+}
+
+function listStyleToNodeType(listItem: string): string | null {
+  if (listItem === 'bullet') return 'unordered-list';
+  if (listItem === 'number') return 'ordered-list';
+  return null;
+}
+
+function convertSpans(spans: PTSpan[], markDefs: PTMarkDef[], warnings: RichTextWarning[]): RichTextNode[] {
+  const markDefMap = new Map(markDefs.map(d => [d._key, d]));
+  const out: RichTextNode[] = [];
+
+  for (const span of spans) {
+    if (!span || span._type !== 'span') continue;
+
+    const text = span.text || '';
+    const inputMarks = span.marks || [];
+
+    // Separate decorators (bold/italic/etc — RichText `marks`) from
+    // annotations (link/custom — RichText structural wrappers).
+    const decorators: Array<{ type: string }> = [];
+    const annotations: PTMarkDef[] = [];
+    for (const mark of inputMarks) {
+      const def = markDefMap.get(mark);
+      if (def) {
+        annotations.push(def);
+      } else if (MARK_TO_RICHTEXT[mark]) {
+        decorators.push({ type: MARK_TO_RICHTEXT[mark] });
+      } else {
+        warnings.push({ code: 'unknown-mark', detail: `Unknown mark "${mark}" dropped (text preserved)` });
+      }
+    }
+
+    let node: RichTextNode = {
+      nodeType: 'text',
+      value: text,
+      marks: decorators,
+      data: {},
+    };
+
+    // Wrap by annotation — last annotation wraps innermost.
+    for (const annotation of annotations) {
+      if (annotation._type === 'link' && typeof annotation.href === 'string') {
+        node = {
+          nodeType: 'hyperlink',
+          data: { uri: annotation.href },
+          content: [node],
+        };
+      } else {
+        warnings.push({
+          code: 'unknown-annotation',
+          detail: `Unknown annotation "${annotation._type}" dropped (text preserved)`,
+        });
+      }
+    }
+
+    out.push(node);
+  }
+
+  return out;
+}
+
+/** True when an array looks like Portable Text (at least one `block` element). */
+export function isPortableText(value: unknown): value is unknown[] {
+  if (!Array.isArray(value) || value.length === 0) return false;
+  return value.some(v => v && typeof v === 'object' && (v as Record<string, unknown>)._type === 'block');
+}
diff --git a/src/sanity/pull-sanity.test.ts b/src/sanity/pull-sanity.test.ts
new file mode 100644
index 0000000..e7e68ee
--- /dev/null
+++ b/src/sanity/pull-sanity.test.ts
@@ -0,0 +1,360 @@
+/**
+ * Tests for src/sanity/pull-sanity.js — M1 (skeleton + output contract).
+ *
+ * These tests guarantee that the output directory shape matches what the
+ * rest of the pipeline (`simulate`, `to-import`, `diff`) consumes: same
+ * shape as `pull` (Contentful) — `contentful-space.json` at the root,
+ * `schemas/<id>.js` per content type, `data/entries.ndjson` with one
+ * JSON-per-line entry.
+ *
+ * Field-type inference (M2) and Portable Text (M5) are tested separately.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+import { pullSanity } from './pull-sanity.js';
+
+// ── Fixture ──────────────────────────────────────────────────────
+
+const FIXTURE = [
+  // system type — must be filtered
+  JSON.stringify({
+    _id: 'system-group-1', _type: 'system.group',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r1',
+    grants: [],
+  }),
+  // image asset — filtered from docs, kept in assets array
+  JSON.stringify({
+    _id: 'image-abc-100x100-jpg', _type: 'sanity.imageAsset',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r2',
+    url: 'https://cdn.sanity.io/x/y/abc-100x100.jpg',
+    originalFilename: 'a.jpg', mimeType: 'image/jpeg', size: 1000,
+    path: 'images/x/y/abc-100x100.jpg',
+  }),
+  // category
+  JSON.stringify({
+    _id: 'cat-1', _type: 'category',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r3',
+    title: 'Tech', slug: { _type: 'slug', current: 'tech' },
+  }),
+  // post #1
+  JSON.stringify({
+    _id: 'post-1', _type: 'post',
+    _createdAt: '2025-03-01T10:00:00Z', _updatedAt: '2025-03-01T12:00:00Z', _rev: 'r4',
+    title: 'Hello', slug: { _type: 'slug', current: 'hello' },
+  }),
+  // post #2
+  JSON.stringify({
+    _id: 'post-2', _type: 'post',
+    _createdAt: '2025-03-02T10:00:00Z', _updatedAt: '2025-03-02T12:00:00Z', _rev: 'r5',
+    title: 'World', slug: { _type: 'slug', current: 'world' },
+  }),
+  // draft post — filtered by default
+  JSON.stringify({
+    _id: 'drafts.post-3', _type: 'post',
+    _createdAt: '2025-03-03T00:00:00Z', _updatedAt: '2025-03-03T00:00:00Z', _rev: 'r6',
+    title: 'Draft',
+  }),
+  // product
+  JSON.stringify({
+    _id: 'product-1', _type: 'product',
+    _createdAt: '2025-02-01T00:00:00Z', _updatedAt: '2025-02-01T00:00:00Z', _rev: 'r7',
+    name: 'Widget', price: 9.99,
+  }),
+].join('\n');
+
+// ── Test scaffolding ─────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pull-sanity-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+/** Read a `schemas/<id>.js` file and return the exported schema object.
+ *  The file is `export default <json>;` — we extract via regex so we don't
+ *  need a dynamic import during tests. */
+function readSchemaFile(filePath: string): unknown {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const match = raw.match(/export default ([\s\S]+);\s*$/);
+  if (!match) throw new Error(`Schema file missing 'export default' shape: ${filePath}`);
+  return JSON.parse(match[1]);
+}
+
+// ── M1: output contract ──────────────────────────────────────────
+
+describe('pullSanity — M1 output contract', () => {
+  it('creates the output directory with the three expected pieces', async () => {
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE });
+    assert.ok(fs.existsSync(path.join(tmpDir, 'contentful-space.json')), 'contentful-space.json missing');
+    assert.ok(fs.existsSync(path.join(tmpDir, 'schemas')), 'schemas/ dir missing');
+    assert.ok(fs.existsSync(path.join(tmpDir, 'data')), 'data/ dir missing');
+    assert.ok(fs.existsSync(path.join(tmpDir, 'data', 'entries.ndjson')), 'data/entries.ndjson missing');
+  });
+
+  it('writes contentful-space.json with locale + source metadata', async () => {
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE, source: 'my-export.ndjson' });
+    const space = JSON.parse(fs.readFileSync(path.join(tmpDir, 'contentful-space.json'), 'utf-8'));
+    assert.equal(space.baseLocale, 'en-US');
+    assert.deepEqual(space.locales, ['en-US']);
+    assert.equal(space.source, 'my-export.ndjson');
+    assert.equal(space.sourceFormat, 'sanity-ndjson');
+    assert.ok(space.pulledAt, 'pulledAt missing');
+    // pulledAt should parse as an ISO date
+    assert.ok(!isNaN(Date.parse(space.pulledAt)), `pulledAt not parseable: ${space.pulledAt}`);
+  });
+
+  it('respects a custom defaultLocale', async () => {
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE, defaultLocale: 'es-MX' });
+    const space = JSON.parse(fs.readFileSync(path.join(tmpDir, 'contentful-space.json'), 'utf-8'));
+    assert.equal(space.baseLocale, 'es-MX');
+    assert.deepEqual(space.locales, ['es-MX']);
+    // entries inherit the same locale
+    const lines = fs.readFileSync(path.join(tmpDir, 'data', 'entries.ndjson'), 'utf-8').trim().split('\n');
+    for (const line of lines) {
+      assert.equal(JSON.parse(line).locale, 'es-MX');
+    }
+  });
+
+  it('writes one schema file per distinct content type', async () => {
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE });
+    const schemaFiles = fs.readdirSync(path.join(tmpDir, 'schemas')).sort();
+    // expected types from fixture (drafts + system + assets filtered): category, post, product
+    assert.deepEqual(schemaFiles, ['category.js', 'post.js', 'product.js']);
+  });
+
+  it('emits schemas with the Contentful shape (id, name, fields[])', async () => {
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE });
+    const postSchema = readSchemaFile(path.join(tmpDir, 'schemas', 'post.js')) as any;
+    assert.equal(postSchema.id, 'post');
+    assert.equal(postSchema.name, 'Post');
+    assert.ok(Array.isArray(postSchema.fields), 'fields must be an array');
+    // M2 fills in inferred fields. The two post docs in the fixture share
+    // `title` (Symbol) and `slug` (Symbol after sanity-reader normalization).
+    const fieldIds = postSchema.fields.map((f: any) => f.id).sort();
+    assert.deepEqual(fieldIds, ['slug', 'title']);
+    assert.equal(postSchema.fields.find((f: any) => f.id === 'title').type, 'Symbol');
+    assert.match(postSchema.description, /Field types inferred automatically/);
+  });
+
+  it('humanizes camelCase content type ids in the schema name', async () => {
+    const fixture = [
+      JSON.stringify({
+        _id: 'a-1', _type: 'blogPost',
+        _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r1',
+        title: 't',
+      }),
+    ].join('\n');
+    await pullSanity({ output: tmpDir, inputContent: fixture });
+    const s = readSchemaFile(path.join(tmpDir, 'schemas', 'blogPost.js')) as any;
+    assert.equal(s.name, 'Blog Post');
+  });
+
+  it('writes entries.ndjson where every line is valid JSON with the entry shape', async () => {
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE });
+    const lines = fs
+      .readFileSync(path.join(tmpDir, 'data', 'entries.ndjson'), 'utf-8')
+      .trim()
+      .split('\n');
+    // 1 category + 2 posts + 1 product = 4 entries (drafts/system/assets filtered)
+    assert.equal(lines.length, 4, `expected 4 entries, got ${lines.length}`);
+    for (const line of lines) {
+      const entry = JSON.parse(line);
+      assert.ok(entry.contentType, 'entry missing contentType');
+      assert.ok(entry.id, 'entry missing id');
+      assert.equal(entry.locale, 'en-US');
+      assert.equal(typeof entry.data, 'object');
+    }
+  });
+
+  it('filters drafts and system types by default; opts in via flags', async () => {
+    // Default — drafts filtered
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE });
+    const linesDefault = fs
+      .readFileSync(path.join(tmpDir, 'data', 'entries.ndjson'), 'utf-8')
+      .trim()
+      .split('\n');
+    const idsDefault = linesDefault.map(l => JSON.parse(l).id);
+    assert.ok(!idsDefault.includes('post-3'), 'draft should not be in default output');
+
+    // With includeDrafts — draft becomes an entry. Re-use tmpDir but rewrite.
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.mkdirSync(tmpDir, { recursive: true });
+    await pullSanity({ output: tmpDir, inputContent: FIXTURE, includeDrafts: true });
+    const idsWithDrafts = fs
+      .readFileSync(path.join(tmpDir, 'data', 'entries.ndjson'), 'utf-8')
+      .trim()
+      .split('\n')
+      .map(l => JSON.parse(l).id);
+    assert.ok(idsWithDrafts.includes('post-3'), 'draft should appear when includeDrafts=true');
+  });
+
+  it('returns the schemas, documents, assets, and warnings in memory too', async () => {
+    const result = await pullSanity({ output: tmpDir, inputContent: FIXTURE });
+    assert.equal(result.schemas.length, 3);
+    assert.equal(result.documents.length, 4);
+    assert.equal(result.assets.length, 1, 'sanity.imageAsset should be collected separately');
+    assert.equal(result.assets[0].mimeType, 'image/jpeg');
+    assert.ok(Array.isArray(result.warnings), 'warnings must be an array (may be empty)');
+    assert.equal(result.output, tmpDir);
+  });
+
+  it('skips writing data/entries.ndjson when there are zero documents', async () => {
+    // Only a system type and an asset — both filtered.
+    const empty = [
+      JSON.stringify({ _id: 's', _type: 'system.group', _createdAt: 'x', _updatedAt: 'x', _rev: 'r' }),
+    ].join('\n');
+    await pullSanity({ output: tmpDir, inputContent: empty });
+    assert.ok(fs.existsSync(path.join(tmpDir, 'contentful-space.json')));
+    assert.ok(!fs.existsSync(path.join(tmpDir, 'data', 'entries.ndjson')), 'should not write entries.ndjson when empty');
+    // schemas/ exists but is empty
+    assert.equal(fs.readdirSync(path.join(tmpDir, 'schemas')).length, 0);
+  });
+
+  it('throws when neither `input` nor `inputContent` is provided', async () => {
+    await assert.rejects(
+      () => pullSanity({ output: tmpDir }),
+      /either `input` .+ or `inputContent` .+ is required/,
+    );
+  });
+});
+
+// ── M4: refs rewritten + linkContentType derived ─────────────────
+
+const M4_FIXTURE = [
+  // Authors
+  JSON.stringify({
+    _id: 'a-1', _type: 'author',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r1',
+    name: 'Alice',
+  }),
+  JSON.stringify({
+    _id: 'a-2', _type: 'author',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r2',
+    name: 'Bob',
+  }),
+  // Categories
+  JSON.stringify({
+    _id: 'c-1', _type: 'category',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r3',
+    title: 'Tech',
+  }),
+  // Tags
+  JSON.stringify({
+    _id: 't-1', _type: 'tag',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r4',
+    label: 'ai',
+  }),
+  JSON.stringify({
+    _id: 't-2', _type: 'tag',
+    _createdAt: '2025-01-01T00:00:00Z', _updatedAt: '2025-01-01T00:00:00Z', _rev: 'r5',
+    label: 'ml',
+  }),
+  // Post #1 — single ref + array of refs
+  JSON.stringify({
+    _id: 'p-1', _type: 'post',
+    _createdAt: '2025-03-01T10:00:00Z', _updatedAt: '2025-03-01T12:00:00Z', _rev: 'r6',
+    title: 'Hello',
+    author: { _type: 'reference', _ref: 'a-1' },
+    category: { _type: 'reference', _ref: 'c-1' },
+    tags: [
+      { _type: 'reference', _ref: 't-1', _key: 'k1' },
+      { _type: 'reference', _ref: 't-2', _key: 'k2' },
+    ],
+  }),
+  // Post #2 — second post with different author target
+  JSON.stringify({
+    _id: 'p-2', _type: 'post',
+    _createdAt: '2025-03-02T10:00:00Z', _updatedAt: '2025-03-02T12:00:00Z', _rev: 'r7',
+    title: 'World',
+    author: { _type: 'reference', _ref: 'a-2' },
+    category: { _type: 'reference', _ref: 'c-1' },
+    tags: [],
+  }),
+].join('\n');
+
+describe('pullSanity — M4 refs + linkContentType', () => {
+  it('rewrites single Sanity refs to Contentful Entry Link shape in entries.ndjson', async () => {
+    await pullSanity({ output: tmpDir, inputContent: M4_FIXTURE });
+    const posts = fs.readFileSync(path.join(tmpDir, 'data', 'entries.ndjson'), 'utf-8')
+      .trim().split('\n').map(l => JSON.parse(l))
+      .filter(e => e.contentType === 'post');
+
+    const p1 = posts.find(p => p.id === 'p-1')!;
+    assert.deepEqual(p1.data.author, { sys: { type: 'Link', linkType: 'Entry', id: 'a-1' } });
+    assert.deepEqual(p1.data.category, { sys: { type: 'Link', linkType: 'Entry', id: 'c-1' } });
+  });
+
+  it('rewrites arrays of refs to arrays of Entry Links, dropping _key', async () => {
+    await pullSanity({ output: tmpDir, inputContent: M4_FIXTURE });
+    const p1 = fs.readFileSync(path.join(tmpDir, 'data', 'entries.ndjson'), 'utf-8')
+      .trim().split('\n').map(l => JSON.parse(l)).find(e => e.id === 'p-1')!;
+    assert.deepEqual(p1.data.tags, [
+      { sys: { type: 'Link', linkType: 'Entry', id: 't-1' } },
+      { sys: { type: 'Link', linkType: 'Entry', id: 't-2' } },
+    ]);
+  });
+
+  it('adds linkContentType validation to single Link Entry fields based on actual targets', async () => {
+    const result = await pullSanity({ output: tmpDir, inputContent: M4_FIXTURE });
+    const postSchema = result.schemas.find(s => s.id === 'post')!;
+    const author = postSchema.fields.find(f => f.id === 'author')!;
+    assert.equal(author.type, 'Link');
+    assert.equal(author.linkType, 'Entry');
+    assert.ok(author.validations, 'author field should have validations');
+    assert.deepEqual(author.validations![0].linkContentType, ['author']);
+
+    const category = postSchema.fields.find(f => f.id === 'category')!;
+    assert.deepEqual(category.validations![0].linkContentType, ['category']);
+  });
+
+  it('adds linkContentType validation to Array<Link Entry>.items based on actual targets', async () => {
+    const result = await pullSanity({ output: tmpDir, inputContent: M4_FIXTURE });
+    const postSchema = result.schemas.find(s => s.id === 'post')!;
+    const tags = postSchema.fields.find(f => f.id === 'tags')!;
+    assert.equal(tags.type, 'Array');
+    assert.equal(tags.items?.type, 'Link');
+    assert.equal(tags.items?.linkType, 'Entry');
+    assert.deepEqual(tags.items?.validations?.[0]?.linkContentType, ['tag']);
+  });
+
+  it('aggregates distinct target types when one field points at multiple content types', async () => {
+    const mixed = [
+      JSON.stringify({ _id: 'a-1', _type: 'author', _createdAt: 'x', _updatedAt: 'x', _rev: 'r1', name: 'a' }),
+      JSON.stringify({ _id: 'c-1', _type: 'category', _createdAt: 'x', _updatedAt: 'x', _rev: 'r2', title: 'c' }),
+      JSON.stringify({
+        _id: 'p-1', _type: 'post', _createdAt: 'x', _updatedAt: 'x', _rev: 'r3',
+        related: { _type: 'reference', _ref: 'a-1' },
+      }),
+      JSON.stringify({
+        _id: 'p-2', _type: 'post', _createdAt: 'x', _updatedAt: 'x', _rev: 'r4',
+        related: { _type: 'reference', _ref: 'c-1' },
+      }),
+    ].join('\n');
+    const result = await pullSanity({ output: tmpDir, inputContent: mixed });
+    const related = result.schemas.find(s => s.id === 'post')!.fields.find(f => f.id === 'related')!;
+    assert.deepEqual(related.validations![0].linkContentType, ['author', 'category']);
+  });
+
+  it('does NOT add linkContentType validation when refs target ids missing from the dataset', async () => {
+    const orphan = [
+      JSON.stringify({
+        _id: 'p-1', _type: 'post', _createdAt: 'x', _updatedAt: 'x', _rev: 'r1',
+        author: { _type: 'reference', _ref: 'gone' },
+      }),
+    ].join('\n');
+    const result = await pullSanity({ output: tmpDir, inputContent: orphan });
+    const author = result.schemas.find(s => s.id === 'post')!.fields.find(f => f.id === 'author')!;
+    // Still typed as Link Entry; just no linkContentType validation.
+    assert.equal(author.type, 'Link');
+    assert.equal(author.validations, undefined);
+  });
+});
diff --git a/src/sanity/pull-sanity.ts b/src/sanity/pull-sanity.ts
new file mode 100644
index 0000000..5496135
--- /dev/null
+++ b/src/sanity/pull-sanity.ts
@@ -0,0 +1,186 @@
+/**
+ * Content Model Simulator — Sanity Pull Adapter
+ *
+ * Reads a Sanity dataset NDJSON export and writes the same output
+ * shape as `pull` (Contentful) — `contentful-space.json`, `schemas/<id>.js`,
+ * and `data/entries.ndjson` — so the rest of the pipeline (`simulate`,
+ * `to-import`, `diff`) consumes the result unchanged.
+ *
+ * Zero-dependency. Reuses `parseSanity` / `parseSanityString` from
+ * `sanity-reader.ts`.
+ *
+ * Status: M1 (skeleton + output contract). Schemas are emitted with
+ * `fields: []` and a TODO description. Field-type inference lands in M2.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { parseSanity, parseSanityString } from './sanity-reader.js';
+import type { SanityImageAsset } from './sanity-reader.js';
+import { inferSchemas } from './sanity-schema-inference.js';
+import type { InferenceWarning } from './sanity-schema-inference.js';
+import { mapDocumentRefs } from './sanity-ref-mapper.js';
+import { mapDocumentAssets, toAssetMetadata } from './sanity-asset-mapper.js';
+import { detectLocales, expandDocumentsByLocale } from './sanity-locale-expander.js';
+import type { ContentTypeDefinition, Document } from '../types.js';
+
+// ── Public API ───────────────────────────────────────────────────
+
+export interface PullSanityOptions {
+  /** Path to the Sanity NDJSON export file. Required unless `inputContent` is provided. */
+  input?: string;
+  /** Output directory. Created recursively if missing. */
+  output: string;
+  /** Default locale to assign to entries (Contentful is locale-first). Defaults to `'en-US'`. */
+  defaultLocale?: string;
+  /** Include draft documents (`_id` prefixed with `drafts.`). Defaults to `false`. */
+  includeDrafts?: boolean;
+  /** Include `sanity.imageAsset` docs as regular entries (in addition to the separate assets array). Defaults to `false`. */
+  includeAssets?: boolean;
+  /** Optional label written to `contentful-space.json` describing the source. Defaults to the `input` path. */
+  source?: string;
+  /** Print progress lines to stdout. Defaults to `false`. */
+  verbose?: boolean;
+  /** Pass NDJSON content directly instead of reading from disk (used in tests). Takes precedence over `input`. */
+  inputContent?: string;
+}
+
+export interface PullSanityResult {
+  schemas: ContentTypeDefinition[];
+  documents: Document[];
+  assets: SanityImageAsset[];
+  warnings: InferenceWarning[];
+  output: string;
+}
+
+export async function pullSanity(options: PullSanityOptions): Promise<PullSanityResult> {
+  const {
+    input,
+    output,
+    defaultLocale = 'en-US',
+    includeDrafts = false,
+    includeAssets = false,
+    verbose = false,
+    source,
+    inputContent,
+  } = options;
+
+  if (inputContent === undefined && !input) {
+    throw new Error('pullSanity: either `input` (file path) or `inputContent` (NDJSON string) is required.');
+  }
+
+  // 1. Parse NDJSON — request RichText for Portable Text so the output is
+  //    Contentful-shaped (rather than the legacy HTML string).
+  const result = inputContent !== undefined
+    ? parseSanityString(inputContent, { includeDrafts, includeAssets, portableText: 'richtext' })
+    : parseSanity(input as string, { includeDrafts, includeAssets, portableText: 'richtext' });
+
+  const { documents, assets } = result;
+  const sourceLabel = source || input || '<inline>';
+  if (verbose) {
+    process.stdout.write(`  Read ${documents.length} document(s), ${assets.length} asset(s) from ${sourceLabel}\n`);
+  }
+
+  // 2. Map Sanity `_ref` refs to Contentful Entry-link shape and harvest
+  //    the per-field set of target content types (used below for the
+  //    `linkContentType` validation on the inferred Link fields).
+  const { documents: refMappedDocs, linkTargets } = mapDocumentRefs(documents);
+
+  // 3. Map Sanity image references (`{_type: 'image', asset: {_ref}}`) to
+  //    the Contentful Link/Asset sys shape. The asset metadata is written
+  //    to `<output>/assets/assets.json` for downstream tooling.
+  const { documents: assetMappedDocs } = mapDocumentAssets(refMappedDocs, assets);
+
+  // 4. Detect i18n shape `{en: …, es: …}` in field values, then fan each
+  //    document out to one per locale (each field gets the locale-specific
+  //    value, falling back to the base locale when missing).
+  const { locales: detectedLocales, localizedFields } = detectLocales(assetMappedDocs);
+  const effectiveLocales = detectedLocales.length > 0 ? detectedLocales : [defaultLocale];
+  const effectiveBaseLocale = detectedLocales.includes(defaultLocale)
+    ? defaultLocale
+    : (effectiveLocales[0] || defaultLocale);
+  const expandedDocs = expandDocumentsByLocale(
+    assetMappedDocs,
+    effectiveLocales,
+    localizedFields,
+    { baseLocale: effectiveBaseLocale },
+  );
+
+  // 5. Group expanded docs by content type for schema inference.
+  const typeGroups = new Map<string, Document[]>();
+  for (const d of expandedDocs) {
+    const t = d.contentType;
+    if (!typeGroups.has(t)) typeGroups.set(t, []);
+    (typeGroups.get(t) as Document[]).push(d);
+  }
+
+  // 6. Infer schemas from the post-expansion `data` payloads (values are
+  //    now scalar within each locale, so Symbol/Text/Date/etc. classify
+  //    correctly). `linkTargets` + `localizedFields` add `linkContentType`
+  //    validations and `localized: true` flags respectively.
+  const samplesByType = new Map(
+    [...typeGroups.entries()].map(([typeId, docs]) => [
+      typeId,
+      docs.map(d => (d.data || {}) as Record<string, unknown>),
+    ]),
+  );
+  const { schemas, warnings } = inferSchemas(samplesByType, { linkTargets, localizedFields });
+
+  if (verbose && warnings.length > 0) {
+    process.stdout.write(`  ${warnings.length} inference warning(s):\n`);
+    for (const w of warnings) {
+      process.stdout.write(`    • [${w.contentTypeId}.${w.fieldId}] ${w.message}\n`);
+    }
+  }
+
+  // 5. Write to disk.
+  mkdirSync(output, { recursive: true });
+
+  const localeConfig = {
+    baseLocale: effectiveBaseLocale,
+    locales: effectiveLocales,
+    pulledAt: new Date().toISOString(),
+    source: sourceLabel,
+    sourceFormat: 'sanity-ndjson',
+  };
+  writeFileSync(
+    join(output, 'contentful-space.json'),
+    JSON.stringify(localeConfig, null, 2) + '\n',
+    'utf-8',
+  );
+
+  const schemasDir = join(output, 'schemas');
+  mkdirSync(schemasDir, { recursive: true });
+  for (const schema of schemas) {
+    const filePath = join(schemasDir, `${schema.id}.js`);
+    const content = `/**\n * ${schema.name}\n * Pulled from Sanity (${sourceLabel})\n */\nexport default ${JSON.stringify(schema, null, 2)};\n`;
+    writeFileSync(filePath, content, 'utf-8');
+  }
+
+  if (expandedDocs.length > 0) {
+    const dataDir = join(output, 'data');
+    mkdirSync(dataDir, { recursive: true });
+    const ndjson = expandedDocs.map(d => JSON.stringify(d)).join('\n') + '\n';
+    writeFileSync(join(dataDir, 'entries.ndjson'), ndjson, 'utf-8');
+  }
+
+  if (assets.length > 0) {
+    const assetsDir = join(output, 'assets');
+    mkdirSync(assetsDir, { recursive: true });
+    const meta = toAssetMetadata(assets);
+    writeFileSync(
+      join(assetsDir, 'assets.json'),
+      JSON.stringify(meta, null, 2) + '\n',
+      'utf-8',
+    );
+  }
+
+  if (verbose) {
+    process.stdout.write(
+      `  Wrote ${schemas.length} schema(s) + ${expandedDocs.length} entry/entries (${effectiveLocales.length} locale${effectiveLocales.length === 1 ? '' : 's'}) + ${assets.length} asset(s) to ${output}\n`,
+    );
+  }
+
+  return { schemas, documents: expandedDocs, assets, warnings, output };
+}
diff --git a/src/sanity/sanity-asset-mapper.test.ts b/src/sanity/sanity-asset-mapper.test.ts
new file mode 100644
index 0000000..85505fb
--- /dev/null
+++ b/src/sanity/sanity-asset-mapper.test.ts
@@ -0,0 +1,176 @@
+/**
+ * Tests for src/sanity/sanity-asset-mapper.js — v0.6.0 M6.
+ *
+ * Verifies that Sanity image references (`{_type: 'image', asset: {_ref}}`)
+ * are rewritten to plain URLs from the asset registry, that orphan refs
+ * (asset id not in the registry) preserve the original shape, and that
+ * `toAssetMetadata` produces the same on-disk shape as pull-contentful.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  buildAssetUrlMap,
+  mapImageRefsToLinks,
+  mapDocumentAssets,
+  toAssetMetadata,
+} from './sanity-asset-mapper.js';
+import type { SanityImageAsset } from './sanity-reader.js';
+import type { Document } from '../types.js';
+
+const SAMPLE_ASSETS: SanityImageAsset[] = [
+  {
+    id: 'image-abc-100x100-jpg',
+    url: 'https://cdn.sanity.io/images/proj/dataset/abc-100x100.jpg',
+    originalFilename: 'hero.jpg',
+    mimeType: 'image/jpeg',
+    size: 50000,
+    path: 'images/proj/dataset/abc-100x100.jpg',
+  },
+  {
+    id: 'image-def-200x200-png',
+    url: 'https://cdn.sanity.io/images/proj/dataset/def-200x200.png',
+    originalFilename: 'logo.png',
+    mimeType: 'image/png',
+    size: 12000,
+    path: 'images/proj/dataset/def-200x200.png',
+  },
+];
+
+// ── buildAssetUrlMap ─────────────────────────────────────────────
+
+describe('buildAssetUrlMap', () => {
+  it('builds an id→url map from the SanityImageAsset[]', () => {
+    const map = buildAssetUrlMap(SAMPLE_ASSETS);
+    assert.equal(map.size, 2);
+    assert.equal(map.get('image-abc-100x100-jpg'), 'https://cdn.sanity.io/images/proj/dataset/abc-100x100.jpg');
+    assert.equal(map.get('image-def-200x200-png'), 'https://cdn.sanity.io/images/proj/dataset/def-200x200.png');
+  });
+});
+
+// ── mapImageRefsToLinks (single value) ───────────────────────────
+
+describe('mapImageRefsToLinks', () => {
+  it('rewrites a top-level image reference to a Contentful Link/Asset sys', () => {
+    const ref = { _type: 'image', asset: { _ref: 'image-abc-100x100-jpg', _type: 'reference' } };
+    const { value, assetIds } = mapImageRefsToLinks(ref);
+    assert.deepEqual(value, { sys: { type: 'Link', linkType: 'Asset', id: 'image-abc-100x100-jpg' } });
+    assert.deepEqual(assetIds, ['image-abc-100x100-jpg']);
+  });
+
+  it('rewrites image references inside arrays', () => {
+    const arr = [
+      { _type: 'image', asset: { _ref: 'image-abc-100x100-jpg' } },
+      { _type: 'image', asset: { _ref: 'image-def-200x200-png' } },
+    ];
+    const { value, assetIds } = mapImageRefsToLinks(arr);
+    assert.deepEqual(value, [
+      { sys: { type: 'Link', linkType: 'Asset', id: 'image-abc-100x100-jpg' } },
+      { sys: { type: 'Link', linkType: 'Asset', id: 'image-def-200x200-png' } },
+    ]);
+    assert.deepEqual(assetIds.sort(), ['image-abc-100x100-jpg', 'image-def-200x200-png']);
+  });
+
+  it('rewrites even when the asset id is not in the dataset (dangling link)', () => {
+    const ref = { _type: 'image', asset: { _ref: 'image-missing' } };
+    const { value, assetIds } = mapImageRefsToLinks(ref);
+    assert.deepEqual(value, { sys: { type: 'Link', linkType: 'Asset', id: 'image-missing' } });
+    assert.deepEqual(assetIds, ['image-missing']);
+  });
+
+  it('recurses into nested objects, rewriting only image shapes', () => {
+    const data = {
+      title: 'Post',
+      hero: { _type: 'image', asset: { _ref: 'image-abc-100x100-jpg' } },
+      meta: {
+        backup: { _type: 'image', asset: { _ref: 'image-def-200x200-png' } },
+      },
+      author: { _type: 'reference', _ref: 'author-1' }, // entry ref — untouched
+    };
+    const { value } = mapImageRefsToLinks(data);
+    assert.deepEqual(value, {
+      title: 'Post',
+      hero: { sys: { type: 'Link', linkType: 'Asset', id: 'image-abc-100x100-jpg' } },
+      meta: { backup: { sys: { type: 'Link', linkType: 'Asset', id: 'image-def-200x200-png' } } },
+      author: { _type: 'reference', _ref: 'author-1' },
+    });
+  });
+
+  it('passes primitives and Link Entry shapes through unchanged', () => {
+    const { value: v1 } = mapImageRefsToLinks('hello');
+    assert.equal(v1, 'hello');
+    const linkEntry = { sys: { type: 'Link', linkType: 'Entry', id: 'x' } };
+    const { value: v2 } = mapImageRefsToLinks(linkEntry);
+    assert.deepEqual(v2, linkEntry);
+  });
+
+  it('does not mutate input', () => {
+    const ref = { _type: 'image', asset: { _ref: 'image-abc-100x100-jpg' } };
+    const snapshot = JSON.parse(JSON.stringify(ref));
+    mapImageRefsToLinks(ref);
+    assert.deepEqual(ref, snapshot);
+  });
+});
+
+// ── mapDocumentAssets ────────────────────────────────────────────
+
+describe('mapDocumentAssets', () => {
+  function doc(id: string, contentType: string, data: Record<string, unknown>): Document {
+    return { id, contentType, data };
+  }
+
+  it('rewrites image refs in every doc.data and returns an assetLinks map', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', {
+        hero: { _type: 'image', asset: { _ref: 'image-abc-100x100-jpg' } },
+      }),
+    ];
+    const { documents, assetLinks } = mapDocumentAssets(docs, SAMPLE_ASSETS);
+    assert.deepEqual(documents[0].data!.hero, {
+      sys: { type: 'Link', linkType: 'Asset', id: 'image-abc-100x100-jpg' },
+    });
+    assert.deepEqual([...(assetLinks.get('post.hero') || [])], ['image-abc-100x100-jpg']);
+  });
+
+  it('omits orphan-only fields from assetLinks', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', {
+        hero: { _type: 'image', asset: { _ref: 'image-missing' } },
+      }),
+    ];
+    const { assetLinks } = mapDocumentAssets(docs, SAMPLE_ASSETS);
+    assert.equal(assetLinks.has('post.hero'), false);
+  });
+});
+
+// ── toAssetMetadata ──────────────────────────────────────────────
+
+describe('toAssetMetadata', () => {
+  it('produces the same shape as pull-contentful assets.json', () => {
+    const meta = toAssetMetadata(SAMPLE_ASSETS);
+    assert.equal(meta.length, 2);
+    assert.deepEqual(meta[0], {
+      id: 'image-abc-100x100-jpg',
+      title: 'hero.jpg',
+      fileName: 'hero.jpg',
+      contentType: 'image/jpeg',
+      url: 'https://cdn.sanity.io/images/proj/dataset/abc-100x100.jpg',
+      size: 50000,
+    });
+  });
+
+  it('falls back to an extension-derived filename when originalFilename is missing', () => {
+    const assets: SanityImageAsset[] = [{
+      id: 'image-xyz',
+      url: 'https://cdn.sanity.io/x.gif',
+      originalFilename: '',
+      mimeType: 'image/gif',
+      size: 0,
+      path: '',
+    }];
+    const [meta] = toAssetMetadata(assets);
+    assert.equal(meta.fileName, 'image-xyz.gif');
+    assert.equal(meta.contentType, 'image/gif');
+  });
+});
diff --git a/src/sanity/sanity-asset-mapper.ts b/src/sanity/sanity-asset-mapper.ts
new file mode 100644
index 0000000..73731b9
--- /dev/null
+++ b/src/sanity/sanity-asset-mapper.ts
@@ -0,0 +1,154 @@
+/**
+ * Content Model Simulator — Sanity Asset Mapper (v0.6.0 M6)
+ *
+ * Walks every document's `data` payload and rewrites Sanity image
+ * references — `{_type: 'image', asset: {_ref}}` (including those nested
+ * in arrays/objects) — into the Contentful `Link/Asset` sys shape that
+ * pull-contentful itself emits:
+ *
+ *     { sys: { type: 'Link', linkType: 'Asset', id: <_ref> } }
+ *
+ * Doing this here (rather than handing the simulator a URL and letting
+ * its WordPress-flavored `extractAssets` discover it) is what eliminates
+ * `ASSET_FIELD_NOT_LINKED` warnings from the validator — the field's
+ * value carries `sys.linkType === 'Asset'`, matches the schema, and the
+ * simulator's link-collection pass picks up `linkedAssetIds` for the
+ * model graph.
+ *
+ * Asset metadata (id / title / url / mime / size) is emitted separately
+ * by `toAssetMetadata` into `<output>/assets/assets.json`, mirroring the
+ * pull-contentful shape so downstream tooling (cms-sim to-import, custom
+ * scripts) can resolve the URLs without re-reading the original NDJSON.
+ *
+ * Orphan references (asset id not in the registry) are still rewritten —
+ * the resulting Link is dangling, but that's a faithful representation
+ * of what the dataset says, and the simulator's link-resolution stage
+ * surfaces dangling links with its own warning.
+ *
+ * Zero-dependency. Pure function (no I/O, no input mutation).
+ */
+
+import type { Document } from '../types.js';
+import type { SanityImageAsset } from './sanity-reader.js';
+
+// ── Public API ───────────────────────────────────────────────────
+
+export interface AssetMapResult {
+  value: unknown;
+  /** Sanity asset `_ref` ids referenced anywhere in the value. */
+  assetIds: string[];
+}
+
+/** Build a lookup from `SanityImageAsset[]` to id → URL. */
+export function buildAssetUrlMap(assets: SanityImageAsset[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const a of assets) {
+    if (a.id && a.url) map.set(a.id, a.url);
+  }
+  return map;
+}
+
+export function mapImageRefsToLinks(value: unknown): AssetMapResult {
+  const assetIds = new Set<string>();
+  const mapped = walk(value, assetIds);
+  return { value: mapped, assetIds: [...assetIds] };
+}
+
+export function mapDocumentAssets(
+  documents: Document[],
+  assets: SanityImageAsset[],
+): {
+  documents: Document[];
+  /** Map of `contentTypeId.fieldId` → set of asset ids actually referenced. */
+  assetLinks: Map<string, Set<string>>;
+} {
+  const assetUrlById = buildAssetUrlMap(assets);
+  const assetLinks = new Map<string, Set<string>>();
+  const out: Document[] = documents.map(d => {
+    const src = (d.data || {}) as Record<string, unknown>;
+    const next: Record<string, unknown> = {};
+    for (const [fieldId, value] of Object.entries(src)) {
+      const { value: mapped, assetIds } = mapImageRefsToLinks(value);
+      next[fieldId] = mapped;
+      if (assetIds.length > 0) {
+        const knownIds = assetIds.filter(id => assetUrlById.has(id));
+        if (knownIds.length > 0) {
+          const key = `${d.contentType}.${fieldId}`;
+          const set = assetLinks.get(key) || new Set<string>();
+          for (const id of knownIds) set.add(id);
+          assetLinks.set(key, set);
+        }
+      }
+    }
+    return { ...d, data: next };
+  });
+  return { documents: out, assetLinks };
+}
+
+// ── Asset metadata writer (mirrors pull-contentful) ──────────────
+
+export interface PullSanityAssetMeta {
+  id: string;
+  title: string;
+  fileName: string;
+  contentType: string;
+  url: string;
+  size: number;
+}
+
+/** Convert the SanityImageAsset[] from sanity-reader into the same shape
+ *  that pull-contentful writes to `assets/assets.json`. */
+export function toAssetMetadata(assets: SanityImageAsset[]): PullSanityAssetMeta[] {
+  return assets.map(a => ({
+    id: a.id,
+    title: a.originalFilename || a.id,
+    fileName: a.originalFilename || `${a.id}.${guessExtension(a.mimeType)}`,
+    contentType: a.mimeType || 'application/octet-stream',
+    url: a.url,
+    size: a.size || 0,
+  }));
+}
+
+// ── Internals ────────────────────────────────────────────────────
+
+function walk(value: unknown, assetIds: Set<string>): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+
+  if (Array.isArray(value)) {
+    return value.map(v => walk(v, assetIds));
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  // Sanity image reference → Contentful Link/Asset sys shape. The asset
+  // id is preserved verbatim from `_ref` so it matches `assets.json`.
+  if (obj._type === 'image' && obj.asset && typeof obj.asset === 'object') {
+    const assetRef = obj.asset as Record<string, unknown>;
+    const refId = typeof assetRef._ref === 'string' ? assetRef._ref : undefined;
+    if (refId) {
+      assetIds.add(refId);
+      return { sys: { type: 'Link', linkType: 'Asset', id: refId } };
+    }
+    return obj;
+  }
+
+  // Recurse into other objects, preserving keys (and leaving entry refs /
+  // RichText documents untouched — they're already shaped correctly).
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    result[k] = walk(v, assetIds);
+  }
+  return result;
+}
+
+function guessExtension(mime: string | undefined): string {
+  if (!mime) return 'bin';
+  if (mime === 'image/jpeg') return 'jpg';
+  if (mime === 'image/png') return 'png';
+  if (mime === 'image/gif') return 'gif';
+  if (mime === 'image/webp') return 'webp';
+  if (mime === 'image/svg+xml') return 'svg';
+  const slash = mime.indexOf('/');
+  return slash > -1 ? mime.slice(slash + 1) : 'bin';
+}
diff --git a/src/sanity/sanity-locale-expander.test.ts b/src/sanity/sanity-locale-expander.test.ts
new file mode 100644
index 0000000..7c43a8a
--- /dev/null
+++ b/src/sanity/sanity-locale-expander.test.ts
@@ -0,0 +1,162 @@
+/**
+ * Tests for src/sanity/sanity-locale-expander.js — v0.6.0 M7.
+ *
+ * Locale detection rules + the expand-by-locale fan-out behaviour.
+ * Covers: positive detection (en, es, pt-BR), negative detection (Link
+ * sys, RichText document, plain field-keyed objects), per-CT-per-field
+ * localized scoping, baseLocale fallback when a locale value is missing,
+ * the no-locales-detected no-op pass-through.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { detectLocales, expandDocumentsByLocale } from './sanity-locale-expander.js';
+import type { Document } from '../types.js';
+
+function doc(id: string, ct: string, data: Record<string, unknown>): Document {
+  return { id, contentType: ct, data };
+}
+
+// ── Detection ────────────────────────────────────────────────────
+
+describe('detectLocales — positive cases', () => {
+  it('detects locales from `{en, es}` shape', () => {
+    const { locales, localizedFields } = detectLocales([
+      doc('p-1', 'post', { title: { en: 'Hi', es: 'Hola' } }),
+    ]);
+    assert.deepEqual(locales, ['en', 'es']);
+    assert.deepEqual([...(localizedFields.get('post') || [])], ['title']);
+  });
+
+  it('detects regional locale codes (en-US, pt-BR)', () => {
+    const { locales } = detectLocales([
+      doc('p-1', 'post', { title: { 'en-US': 'Hi', 'pt-BR': 'Oi' } }),
+    ]);
+    assert.deepEqual(locales.sort(), ['en-US', 'pt-BR']);
+  });
+
+  it('detects a singleton locale object', () => {
+    const { locales } = detectLocales([
+      doc('p-1', 'post', { title: { en: 'Hi' } }),
+    ]);
+    assert.deepEqual(locales, ['en']);
+  });
+
+  it('aggregates locales across multiple docs / fields', () => {
+    const { locales, localizedFields } = detectLocales([
+      doc('p-1', 'post', { title: { en: 'Hi' }, subtitle: { en: 'Sub' } }),
+      doc('p-2', 'post', { title: { es: 'Hola' } }),
+      doc('a-1', 'author', { bio: { en: 'B' } }),
+    ]);
+    assert.deepEqual(locales.sort(), ['en', 'es']);
+    assert.deepEqual([...(localizedFields.get('post') || [])].sort(), ['subtitle', 'title']);
+    assert.deepEqual([...(localizedFields.get('author') || [])], ['bio']);
+  });
+});
+
+describe('detectLocales — negative cases', () => {
+  it('ignores Sanity refs and image shapes (have `_type`)', () => {
+    const { locales, localizedFields } = detectLocales([
+      doc('p-1', 'post', {
+        category: { _type: 'reference', _ref: 'c-1' },
+        hero: { _type: 'image', asset: { _ref: 'image-x' } },
+      }),
+    ]);
+    assert.deepEqual(locales, []);
+    assert.equal(localizedFields.size, 0);
+  });
+
+  it('ignores Contentful Link sys shapes', () => {
+    const { locales } = detectLocales([
+      doc('p-1', 'post', { author: { sys: { type: 'Link', linkType: 'Entry', id: 'a-1' } } }),
+    ]);
+    assert.deepEqual(locales, []);
+  });
+
+  it('ignores RichText documents', () => {
+    const { locales } = detectLocales([
+      doc('p-1', 'post', { body: { nodeType: 'document', data: {}, content: [] } }),
+    ]);
+    assert.deepEqual(locales, []);
+  });
+
+  it('ignores objects with arbitrary keys (not all locale codes)', () => {
+    const { locales } = detectLocales([
+      doc('p-1', 'post', { meta: { title: 'x', description: 'y' } }),
+    ]);
+    assert.deepEqual(locales, []);
+  });
+
+  it('ignores empty objects', () => {
+    const { locales } = detectLocales([
+      doc('p-1', 'post', { meta: {} }),
+    ]);
+    assert.deepEqual(locales, []);
+  });
+});
+
+// ── Expansion ────────────────────────────────────────────────────
+
+describe('expandDocumentsByLocale', () => {
+  it('emits one Document per locale with the locale-specific value', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { title: { en: 'Hi', es: 'Hola' } }),
+    ];
+    const { locales, localizedFields } = detectLocales(docs);
+    const expanded = expandDocumentsByLocale(docs, locales, localizedFields, { baseLocale: 'en' });
+    assert.equal(expanded.length, 2);
+    const byLocale = Object.fromEntries(expanded.map(d => [d.locale, d.data!.title]));
+    assert.equal(byLocale.en, 'Hi');
+    assert.equal(byLocale.es, 'Hola');
+  });
+
+  it('preserves non-localized fields verbatim across locale variants', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', {
+        title: { en: 'Hi', es: 'Hola' },
+        slug: 'hello',
+        author: { sys: { type: 'Link', linkType: 'Entry', id: 'a-1' } },
+      }),
+    ];
+    const { locales, localizedFields } = detectLocales(docs);
+    const expanded = expandDocumentsByLocale(docs, locales, localizedFields, { baseLocale: 'en' });
+    for (const e of expanded) {
+      assert.equal(e.data!.slug, 'hello');
+      assert.deepEqual(e.data!.author, { sys: { type: 'Link', linkType: 'Entry', id: 'a-1' } });
+    }
+  });
+
+  it('falls back to baseLocale value when a locale is missing for a field', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { title: { en: 'Hi' } }), // 'es' missing
+    ];
+    const { localizedFields } = detectLocales(docs);
+    const expanded = expandDocumentsByLocale(docs, ['en', 'es'], localizedFields, { baseLocale: 'en' });
+    const esDoc = expanded.find(d => d.locale === 'es');
+    assert.ok(esDoc, 'expected an es variant');
+    assert.equal(esDoc.data!.title, 'Hi'); // baseLocale fallback
+  });
+
+  it('is a no-op when no locale-shaped fields are present (just tags with baseLocale)', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { title: 'Hi', slug: 'hello' }),
+    ];
+    const { locales, localizedFields } = detectLocales(docs);
+    assert.deepEqual(locales, []);
+    const expanded = expandDocumentsByLocale(docs, locales, localizedFields, { baseLocale: 'en' });
+    assert.equal(expanded.length, 1);
+    assert.equal(expanded[0].locale, 'en');
+    assert.equal(expanded[0].data!.title, 'Hi');
+  });
+
+  it('does not mutate input documents', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { title: { en: 'Hi', es: 'Hola' } }),
+    ];
+    const snapshot = JSON.parse(JSON.stringify(docs));
+    const { locales, localizedFields } = detectLocales(docs);
+    expandDocumentsByLocale(docs, locales, localizedFields, { baseLocale: 'en' });
+    assert.deepEqual(docs, snapshot);
+  });
+});
diff --git a/src/sanity/sanity-locale-expander.ts b/src/sanity/sanity-locale-expander.ts
new file mode 100644
index 0000000..d5965de
--- /dev/null
+++ b/src/sanity/sanity-locale-expander.ts
@@ -0,0 +1,124 @@
+/**
+ * Content Model Simulator — Sanity Locale Detector + Expander (v0.6.0 M7)
+ *
+ * Detects locale-shaped values in normalized Sanity documents
+ * (`{en: '…', es: '…'}` — a plain object whose keys all match a locale
+ * code pattern) and rewrites the corpus so each `Document` carries
+ * exactly one locale tag, mirroring what `cms-sim simulate` expects.
+ *
+ * Without this pass the schema-inference step classifies localized
+ * fields as plain `Object` and the simulator can't merge entries across
+ * locale variants. With it, each Sanity doc fans out to N docs (one per
+ * locale found), each field whose value was `{en, es}` collapses to that
+ * locale's value, and the inferred schema marks the field `localized:
+ * true`.
+ *
+ * Locale detection rules:
+ * - Object's keys all match `^[a-z]{2,3}(-[A-Z]{2})?$` (e.g., `en`,
+ *   `en-US`, `pt-BR`).
+ * - No `_type`, `sys`, or `nodeType` keys (avoids treating Sanity
+ *   special types, Link shapes, or RichText documents as locales).
+ * - At least one key.
+ *
+ * Localization is detected per (contentType, field) so the same field
+ * name across two CTs can be localized in one and not the other.
+ *
+ * Pure functions, zero-dependency, no input mutation.
+ */
+
+import type { Document } from '../types.js';
+
+// ── Public API ───────────────────────────────────────────────────
+
+export interface LocaleDetectionResult {
+  /** Distinct locale codes observed across all locale-shaped values. */
+  locales: string[];
+  /** Map of `contentTypeId` → set of field ids that are localized. */
+  localizedFields: Map<string, Set<string>>;
+}
+
+export function detectLocales(documents: Document[]): LocaleDetectionResult {
+  const locales = new Set<string>();
+  const localizedFields = new Map<string, Set<string>>();
+
+  for (const d of documents) {
+    const data = (d.data || {}) as Record<string, unknown>;
+    for (const [fieldId, value] of Object.entries(data)) {
+      const keys = localeShapeKeys(value);
+      if (!keys) continue;
+      keys.forEach(k => locales.add(k));
+      const ctSet = localizedFields.get(d.contentType) || new Set<string>();
+      ctSet.add(fieldId);
+      localizedFields.set(d.contentType, ctSet);
+    }
+  }
+
+  return { locales: [...locales].sort(), localizedFields };
+}
+
+export interface ExpandOptions {
+  /** The base locale (used as fallback when a doc is missing a value for some locale). */
+  baseLocale: string;
+}
+
+export function expandDocumentsByLocale(
+  documents: Document[],
+  locales: string[],
+  localizedFields: Map<string, Set<string>>,
+  options: ExpandOptions,
+): Document[] {
+  const { baseLocale } = options;
+  if (locales.length === 0) {
+    // No multi-locale detected — just tag every doc with the base locale.
+    return documents.map(d => ({ ...d, locale: d.locale || baseLocale }));
+  }
+
+  const out: Document[] = [];
+  for (const d of documents) {
+    const ctLocalized = localizedFields.get(d.contentType) || new Set<string>();
+    const data = (d.data || {}) as Record<string, unknown>;
+
+    for (const locale of locales) {
+      const next: Record<string, unknown> = {};
+      for (const [fieldId, value] of Object.entries(data)) {
+        if (ctLocalized.has(fieldId) && localeShapeKeys(value)) {
+          const obj = value as Record<string, unknown>;
+          // Prefer the exact locale, fall back to baseLocale, then any value.
+          if (locale in obj) next[fieldId] = obj[locale];
+          else if (baseLocale in obj) next[fieldId] = obj[baseLocale];
+          // Otherwise: leave the field out for this locale (Contentful treats
+          // it as null/empty, which is the closest equivalent).
+        } else {
+          next[fieldId] = value;
+        }
+      }
+      // Only emit the locale variant when at least one localized field has a
+      // value, OR the doc has at least one non-localized field. (An entirely
+      // empty doc is meaningless.)
+      if (Object.keys(next).length > 0) {
+        out.push({ ...d, locale, data: next });
+      }
+    }
+  }
+  return out;
+}
+
+// ── Internals ────────────────────────────────────────────────────
+
+/** Locale code: ISO 639-1/2 lowercase + optional ISO 3166 uppercase. */
+const LOCALE_CODE_RE = /^[a-z]{2,3}(-[A-Z]{2})?$/;
+
+/**
+ * Returns the array of locale-key strings if `value` is a locale-shaped
+ * object, otherwise `null`. Caller uses the truthy check.
+ */
+function localeShapeKeys(value: unknown): string[] | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const obj = value as Record<string, unknown>;
+  // Skip Sanity special types, Contentful Link shapes, RichText documents.
+  if ('_type' in obj || 'sys' in obj || 'nodeType' in obj) return null;
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return null;
+  if (!keys.every(k => LOCALE_CODE_RE.test(k))) return null;
+  return keys;
+}
diff --git a/src/sanity/sanity-reader.ts b/src/sanity/sanity-reader.ts
index 72d7a2b..74f0c87 100644
--- a/src/sanity/sanity-reader.ts
+++ b/src/sanity/sanity-reader.ts
@@ -17,6 +17,7 @@
 import fs from 'fs';
 import path from 'path';
 import type { Document } from '../types.js';
+import { portableTextToRichText } from './portable-text-to-richtext.js';
 
 // ── Types ────────────────────────────────────────────────────────
 
@@ -27,6 +28,11 @@ export interface SanityReadOptions {
   includeSystemTypes?: boolean;
   /** Include `sanity.imageAsset` documents as regular documents. Defaults to false. */
   includeAssets?: boolean;
+  /** How to handle Portable Text arrays embedded in field values:
+   *  - `'html'` (default): collapse to an HTML string via `portableTextToHTML`.
+   *  - `'richtext'`: emit a Contentful RichText document via `portableTextToRichText`.
+   *  - `'raw'`: leave the array of PT blocks untouched. */
+  portableText?: 'html' | 'richtext' | 'raw';
 }
 
 export interface SanityImageAsset {
@@ -103,7 +109,7 @@ export function parseSanity(filePath: string, options: SanityReadOptions = {}):
  * Parse a Sanity NDJSON string directly (useful for testing without file I/O).
  */
 export function parseSanityString(ndjson: string, options: SanityReadOptions = {}): SanityResult {
-  const { includeDrafts = false, includeSystemTypes = false, includeAssets = false } = options;
+  const { includeDrafts = false, includeSystemTypes = false, includeAssets = false, portableText = 'html' } = options;
 
   const documents: Document[] = [];
   const assets: SanityImageAsset[] = [];
@@ -139,7 +145,7 @@ export function parseSanityString(ndjson: string, options: SanityReadOptions = {
     const data: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(raw)) {
       if (SYSTEM_FIELDS.has(key)) continue;
-      data[key] = normalizeField(value);
+      data[key] = normalizeField(value, portableText);
     }
 
     // Extract slug for path
@@ -160,17 +166,27 @@ export function parseSanityString(ndjson: string, options: SanityReadOptions = {
 
 /**
  * Recursively normalize Sanity field values to plain data.
+ *
+ * The `ptMode` argument controls how Portable Text arrays are emitted:
+ *   - `'html'`     → HTML string via `portableTextToHTML` (legacy default).
+ *   - `'richtext'` → Contentful RichText document via `portableTextToRichText`.
+ *   - `'raw'`      → leave PT blocks untouched.
  */
-function normalizeField(value: unknown): unknown {
+function normalizeField(value: unknown, ptMode: 'html' | 'richtext' | 'raw' = 'html'): unknown {
   if (value === null || value === undefined) return value;
   if (typeof value !== 'object') return value;
 
   if (Array.isArray(value)) {
     // Check if this is an array of Portable Text blocks
     if (isPortableTextArray(value)) {
+      if (ptMode === 'richtext') {
+        const { document } = portableTextToRichText(value);
+        return document;
+      }
+      if (ptMode === 'raw') return value;
       return portableTextToHTML(value);
     }
-    return value.map(normalizeField);
+    return value.map(v => normalizeField(v, ptMode));
   }
 
   const obj = value as Record<string, unknown>;
@@ -195,7 +211,7 @@ function normalizeField(value: unknown): unknown {
     const result: Record<string, unknown> = {};
     for (const [key, val] of Object.entries(obj)) {
       if (key === '_type') continue;
-      result[key] = normalizeField(val);
+      result[key] = normalizeField(val, ptMode);
     }
     return result;
   }
@@ -203,8 +219,13 @@ function normalizeField(value: unknown): unknown {
   // Generic object without _type that has locale keys (en/es pattern)
   // These are NOT normalized here — they stay as objects for transforms
 
-  // Portable Text block → convert to HTML
+  // Portable Text block → convert to HTML / RichText / leave raw
   if (obj._type === 'block' && Array.isArray(obj.children)) {
+    if (ptMode === 'richtext') {
+      const { document } = portableTextToRichText([obj]);
+      return document;
+    }
+    if (ptMode === 'raw') return obj;
     return portableTextToHTML([obj]);
   }
 
@@ -212,7 +233,7 @@ function normalizeField(value: unknown): unknown {
   const result: Record<string, unknown> = {};
   for (const [key, val] of Object.entries(obj)) {
     if (key === '_key') continue; // Strip internal keys
-    result[key] = normalizeField(val);
+    result[key] = normalizeField(val, ptMode);
   }
   return result;
 }
diff --git a/src/sanity/sanity-ref-mapper.test.ts b/src/sanity/sanity-ref-mapper.test.ts
new file mode 100644
index 0000000..3e47f4a
--- /dev/null
+++ b/src/sanity/sanity-ref-mapper.test.ts
@@ -0,0 +1,178 @@
+/**
+ * Tests for src/sanity/sanity-ref-mapper.js — v0.6.0 M4.
+ *
+ * Verifies that `{_type: 'reference', _ref}` shapes — including those
+ * nested in arrays, in plain objects, and in deeply nested structures —
+ * are rewritten to the Contentful Entry-link shape
+ * `{ sys: { type: 'Link', linkType: 'Entry', id: <_ref> } }`. Asset
+ * references (`{_type: 'image', asset: {_ref}}`) are intentionally left
+ * unchanged here (M6 handles those).
+ *
+ * Also verifies `mapDocumentRefs` produces the cross-content-type
+ * `linkTargets` table used downstream for inferring
+ * `linkContentType` validations.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { mapRefsToContentful, mapDocumentRefs } from './sanity-ref-mapper.js';
+import type { Document } from '../types.js';
+
+// ── mapRefsToContentful — single-value transform ─────────────────
+
+describe('mapRefsToContentful — single ref', () => {
+  it('rewrites a top-level Sanity reference to a Contentful Entry Link', () => {
+    const { value, refIds } = mapRefsToContentful({ _type: 'reference', _ref: 'doc-1' });
+    assert.deepEqual(value, { sys: { type: 'Link', linkType: 'Entry', id: 'doc-1' } });
+    assert.deepEqual(refIds, ['doc-1']);
+  });
+
+  it('preserves extra ref metadata by dropping it (_key, _weak, _strengthenOnPublish)', () => {
+    const { value } = mapRefsToContentful({
+      _type: 'reference', _ref: 'doc-1', _key: 'abc', _weak: true, _strengthenOnPublish: false,
+    });
+    // Resulting Link should be the canonical Contentful shape only.
+    assert.deepEqual(value, { sys: { type: 'Link', linkType: 'Entry', id: 'doc-1' } });
+  });
+
+  it('rewrites refs inside arrays', () => {
+    const { value, refIds } = mapRefsToContentful([
+      { _type: 'reference', _ref: 't-1' },
+      { _type: 'reference', _ref: 't-2' },
+    ]);
+    assert.deepEqual(value, [
+      { sys: { type: 'Link', linkType: 'Entry', id: 't-1' } },
+      { sys: { type: 'Link', linkType: 'Entry', id: 't-2' } },
+    ]);
+    assert.deepEqual(refIds.sort(), ['t-1', 't-2']);
+  });
+
+  it('recurses into plain objects, rewriting nested refs', () => {
+    const { value, refIds } = mapRefsToContentful({
+      author: { _type: 'reference', _ref: 'a-1' },
+      meta: { related: { _type: 'reference', _ref: 'a-2' } },
+    });
+    assert.deepEqual(value, {
+      author: { sys: { type: 'Link', linkType: 'Entry', id: 'a-1' } },
+      meta: { related: { sys: { type: 'Link', linkType: 'Entry', id: 'a-2' } } },
+    });
+    assert.deepEqual(refIds.sort(), ['a-1', 'a-2']);
+  });
+
+  it('does NOT rewrite image references (M6 handles asset links separately)', () => {
+    const image = { _type: 'image', asset: { _ref: 'image-abc', _type: 'reference' } };
+    const { value, refIds } = mapRefsToContentful(image);
+    // Image shape preserved end-to-end — inner asset ref is not classified
+    // as an entry link, so it must not appear in refIds and the asset object
+    // must keep its original shape.
+    assert.equal((value as any)._type, 'image');
+    assert.equal((value as any).asset._ref, 'image-abc');
+    assert.equal((value as any).asset._type, 'reference');
+    assert.deepEqual(refIds, []);
+  });
+
+  it('passes through primitives and null/undefined', () => {
+    assert.equal(mapRefsToContentful('hello').value, 'hello');
+    assert.equal(mapRefsToContentful(42).value, 42);
+    assert.equal(mapRefsToContentful(true).value, true);
+    assert.equal(mapRefsToContentful(null).value, null);
+    assert.equal(mapRefsToContentful(undefined).value, undefined);
+  });
+
+  it('does not mutate the input value', () => {
+    const input = { _type: 'reference', _ref: 'x' };
+    const snapshot = JSON.parse(JSON.stringify(input));
+    mapRefsToContentful(input);
+    assert.deepEqual(input, snapshot);
+  });
+
+  it('returns an empty refIds list when no refs are present', () => {
+    const { refIds } = mapRefsToContentful({ title: 'Hello', count: 3, nested: { tags: ['a', 'b'] } });
+    assert.deepEqual(refIds, []);
+  });
+});
+
+// ── mapDocumentRefs — cross-document linkTargets ────────────────
+
+describe('mapDocumentRefs', () => {
+  function doc(id: string, contentType: string, data: Record<string, unknown>): Document {
+    return { id, contentType, data };
+  }
+
+  it('rewrites refs in every doc.data and returns a per-field linkTargets map', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { author: { _type: 'reference', _ref: 'a-1' } }),
+      doc('a-1', 'author', { name: 'Alice' }),
+    ];
+    const { documents, linkTargets } = mapDocumentRefs(docs);
+
+    // Post.author rewritten.
+    assert.deepEqual(
+      documents[0].data!.author,
+      { sys: { type: 'Link', linkType: 'Entry', id: 'a-1' } },
+    );
+    // Author untouched (no refs).
+    assert.deepEqual(documents[1].data!.name, 'Alice');
+
+    // linkTargets resolves 'post.author' → ['author']
+    assert.deepEqual([...(linkTargets.get('post.author') || [])], ['author']);
+  });
+
+  it('aggregates distinct target content types across docs', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { related: { _type: 'reference', _ref: 'a-1' } }),
+      doc('p-2', 'post', { related: { _type: 'reference', _ref: 'c-1' } }),
+      doc('a-1', 'author', {}),
+      doc('c-1', 'category', {}),
+    ];
+    const { linkTargets } = mapDocumentRefs(docs);
+    const targets = [...(linkTargets.get('post.related') || [])].sort();
+    assert.deepEqual(targets, ['author', 'category']);
+  });
+
+  it('handles arrays of refs (tags pattern)', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', {
+        tags: [
+          { _type: 'reference', _ref: 't-1', _key: 'k1' },
+          { _type: 'reference', _ref: 't-2', _key: 'k2' },
+        ],
+      }),
+      doc('t-1', 'tag', {}),
+      doc('t-2', 'tag', {}),
+    ];
+    const { documents, linkTargets } = mapDocumentRefs(docs);
+    assert.deepEqual(
+      documents[0].data!.tags,
+      [
+        { sys: { type: 'Link', linkType: 'Entry', id: 't-1' } },
+        { sys: { type: 'Link', linkType: 'Entry', id: 't-2' } },
+      ],
+    );
+    assert.deepEqual([...(linkTargets.get('post.tags') || [])], ['tag']);
+  });
+
+  it('omits orphan refs from linkTargets (target id not in doc set)', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { author: { _type: 'reference', _ref: 'missing' } }),
+    ];
+    const { documents, linkTargets } = mapDocumentRefs(docs);
+    // Ref still rewritten — just no target type added.
+    assert.deepEqual(
+      documents[0].data!.author,
+      { sys: { type: 'Link', linkType: 'Entry', id: 'missing' } },
+    );
+    // The fieldKey is created but the set is empty → we drop it.
+    assert.equal(linkTargets.has('post.author'), false);
+  });
+
+  it('does not mutate the input documents', () => {
+    const docs: Document[] = [
+      doc('p-1', 'post', { author: { _type: 'reference', _ref: 'a-1' } }),
+    ];
+    const snapshot = JSON.parse(JSON.stringify(docs));
+    mapDocumentRefs(docs);
+    assert.deepEqual(docs, snapshot);
+  });
+});
diff --git a/src/sanity/sanity-ref-mapper.ts b/src/sanity/sanity-ref-mapper.ts
new file mode 100644
index 0000000..c2b1597
--- /dev/null
+++ b/src/sanity/sanity-ref-mapper.ts
@@ -0,0 +1,127 @@
+/**
+ * Content Model Simulator — Sanity → Contentful Reference Mapper (v0.6.0 M4)
+ *
+ * Walks a normalized Sanity document `data` payload and rewrites
+ * `{_type: 'reference', _ref}` shapes (including those nested in
+ * arrays and objects) into the Contentful Entry-link shape:
+ *
+ *     { sys: { type: 'Link', linkType: 'Entry', id: <_ref> } }
+ *
+ * This is what lets the simulator's link-resolution stage (`resolveLinks`)
+ * pick up the references and populate `linkedEntryIds` on each entry,
+ * and what makes the model graph draw arrows between content types from
+ * real data — not just from schema-level `linkContentType` validations.
+ *
+ * Asset references — `{_type: 'image', asset: {_ref}}` — are intentionally
+ * left untouched here. M6 (assets) handles those alongside the asset
+ * extraction pass; touching them now would emit Link Asset nodes whose
+ * targets don't yet exist in the simulator's asset registry.
+ *
+ * Zero-dependency. Pure function (no I/O, no mutation of input).
+ *
+ * Optionally returns the set of distinct target content types observed
+ * per field path, which the inference step uses to derive
+ * `linkContentType` validations on the resulting schemas.
+ */
+
+import type { Document } from '../types.js';
+
+// ── Public API ───────────────────────────────────────────────────
+
+export interface RefMapResult {
+  /** The transformed value with refs rewritten in place (deep copy). */
+  value: unknown;
+  /** Source-doc IDs referenced anywhere within the value (deduplicated). */
+  refIds: string[];
+}
+
+/**
+ * Transform a single value (object/array/primitive) rewriting Sanity refs.
+ * Does not need a target-type map — pure shape transformation.
+ */
+export function mapRefsToContentful(value: unknown): RefMapResult {
+  const refIds = new Set<string>();
+  const mapped = walk(value, refIds);
+  return { value: mapped, refIds: [...refIds] };
+}
+
+/**
+ * Apply the ref mapping to every document's `data` payload.
+ *
+ * Returns a parallel array of `Document`s (input not mutated) plus the
+ * per-(contentType, field) set of target content types observed — useful
+ * for deriving Contentful `linkContentType` validations on schemas.
+ */
+export function mapDocumentRefs(documents: Document[]): {
+  documents: Document[];
+  /** Map of `contentTypeId.fieldId` → Set of distinct target content type ids. */
+  linkTargets: Map<string, Set<string>>;
+} {
+  // First pass — build an id → contentType lookup so we can resolve targets.
+  const idToType = new Map<string, string>();
+  for (const d of documents) {
+    if (d.id) idToType.set(d.id, d.contentType);
+  }
+
+  const linkTargets = new Map<string, Set<string>>();
+  const out: Document[] = documents.map(d => {
+    const sourceData = (d.data || {}) as Record<string, unknown>;
+    const newData: Record<string, unknown> = {};
+    for (const [fieldId, fieldValue] of Object.entries(sourceData)) {
+      const { value: newValue, refIds } = mapRefsToContentful(fieldValue);
+      newData[fieldId] = newValue;
+      if (refIds.length > 0) {
+        const key = `${d.contentType}.${fieldId}`;
+        const set = linkTargets.get(key) || new Set<string>();
+        for (const refId of refIds) {
+          const targetType = idToType.get(refId);
+          if (targetType) set.add(targetType);
+        }
+        if (set.size > 0) linkTargets.set(key, set);
+      }
+    }
+    return { ...d, data: newData };
+  });
+
+  return { documents: out, linkTargets };
+}
+
+// ── Internals ────────────────────────────────────────────────────
+
+function walk(value: unknown, refIds: Set<string>): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+
+  if (Array.isArray(value)) {
+    return value.map(v => walk(v, refIds));
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  // Sanity reference → Contentful Entry Link.
+  if (obj._type === 'reference' && typeof obj._ref === 'string') {
+    refIds.add(obj._ref);
+    return {
+      sys: {
+        type: 'Link',
+        linkType: 'Entry',
+        id: obj._ref,
+      },
+    };
+  }
+
+  // Image references are NOT entry references — M6 will reshape the
+  // whole `{_type: 'image', asset: {_ref}}` to a Link Asset later. Until
+  // then we hand it back untouched so the inner `asset._ref` doesn't get
+  // misclassified as an entry link.
+  if (obj._type === 'image' && obj.asset && typeof obj.asset === 'object') {
+    return obj;
+  }
+
+  // Recurse into other objects, preserving keys.
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    result[k] = walk(v, refIds);
+  }
+  return result;
+}
diff --git a/src/sanity/sanity-schema-inference.test.ts b/src/sanity/sanity-schema-inference.test.ts
new file mode 100644
index 0000000..858b654
--- /dev/null
+++ b/src/sanity/sanity-schema-inference.test.ts
@@ -0,0 +1,206 @@
+/**
+ * Tests for src/sanity/sanity-schema-inference.js — v0.6.0 M2.
+ *
+ * Field-type inference is what differentiates a useful pull from a
+ * placeholder. These tests cover the per-shape mapping (string sizes,
+ * numbers, booleans, dates, refs, images, arrays of each), the
+ * dominant-shape selection under disagreement (with warning), the
+ * presence-based `required` flag, and the few "no perfect mapping"
+ * fallbacks (mixed arrays, unknown shapes).
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { inferSchemas } from './sanity-schema-inference.js';
+import type { DocumentSamplesByType } from './sanity-schema-inference.js';
+
+function group(typeId: string, docs: Array<Record<string, unknown>>): DocumentSamplesByType {
+  return new Map([[typeId, docs]]);
+}
+
+// ── Primitive types ──────────────────────────────────────────────
+
+describe('inferSchemas — primitive shapes', () => {
+  it('infers Symbol for short strings and Text for long strings', () => {
+    const long = 'x'.repeat(300);
+    const { schemas } = inferSchemas(group('post', [
+      { title: 'short title', body: long },
+      { title: 'another', body: long },
+    ]));
+    const fields = schemas[0].fields;
+    assert.equal(fields.find(f => f.id === 'title')!.type, 'Symbol');
+    assert.equal(fields.find(f => f.id === 'body')!.type, 'Text');
+  });
+
+  it('infers Integer vs Number', () => {
+    const { schemas } = inferSchemas(group('product', [
+      { stock: 5, price: 9.99 },
+      { stock: 10, price: 12.50 },
+    ]));
+    const f = (id: string) => schemas[0].fields.find(x => x.id === id)!;
+    assert.equal(f('stock').type, 'Integer');
+    assert.equal(f('price').type, 'Number');
+  });
+
+  it('infers Boolean', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { featured: true }, { featured: false },
+    ]));
+    assert.equal(schemas[0].fields[0].type, 'Boolean');
+  });
+
+  it('infers Date for ISO 8601 strings', () => {
+    const { schemas } = inferSchemas(group('event', [
+      { publishedAt: '2025-05-01T10:00:00Z', dateOnly: '2025-05-01' },
+    ]));
+    const f = (id: string) => schemas[0].fields.find(x => x.id === id)!;
+    assert.equal(f('publishedAt').type, 'Date');
+    assert.equal(f('dateOnly').type, 'Date');
+  });
+});
+
+// ── Sanity-specific shapes ───────────────────────────────────────
+
+describe('inferSchemas — Sanity-specific shapes', () => {
+  it('infers Link (Entry) for { _type: reference, _ref }', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { author: { _type: 'reference', _ref: 'author-1' } },
+      { author: { _type: 'reference', _ref: 'author-2' } },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Link');
+    assert.equal(f.linkType, 'Entry');
+  });
+
+  it('infers Link (Asset) for { _type: image, asset: {_ref} }', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { hero: { _type: 'image', asset: { _ref: 'image-abc', _type: 'reference' } } },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Link');
+    assert.equal(f.linkType, 'Asset');
+  });
+
+  it('infers Array<Link Entry> for arrays of references', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { tags: [
+        { _type: 'reference', _ref: 't-1' },
+        { _type: 'reference', _ref: 't-2' },
+      ] },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Array');
+    assert.deepEqual(f.items, { type: 'Link', linkType: 'Entry' });
+  });
+
+  it('infers Array<Link Asset> for arrays of images', () => {
+    const { schemas } = inferSchemas(group('gallery', [
+      { photos: [
+        { _type: 'image', asset: { _ref: 'a' } },
+        { _type: 'image', asset: { _ref: 'b' } },
+      ] },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Array');
+    assert.deepEqual(f.items, { type: 'Link', linkType: 'Asset' });
+  });
+
+  it('infers Array<Symbol> for arrays of short strings', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { keywords: ['a', 'b', 'c'] },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Array');
+    assert.deepEqual(f.items, { type: 'Symbol' });
+  });
+
+  it('infers Object for plain key/value objects', () => {
+    const { schemas } = inferSchemas(group('feature', [
+      { title: { en: 'Power', es: 'Potencia' } },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Object');
+  });
+});
+
+// ── Disagreement & warnings ──────────────────────────────────────
+
+describe('inferSchemas — disagreement handling', () => {
+  it('picks the majority shape and emits a type-conflict warning', () => {
+    // 4 strings, 1 number — string should win, with a warning.
+    const { schemas, warnings } = inferSchemas(group('mixed', [
+      { value: 'a' }, { value: 'b' }, { value: 'c' }, { value: 'd' }, { value: 1 },
+    ]));
+    assert.equal(schemas[0].fields[0].type, 'Symbol');
+    assert.equal(warnings.length, 1);
+    assert.equal(warnings[0].code, 'type-conflict');
+    assert.equal(warnings[0].fieldId, 'value');
+    assert.match(warnings[0].message, /mixed value shapes/);
+  });
+
+  it('collapses mixed-content arrays to Object with a warning', () => {
+    const { schemas, warnings } = inferSchemas(group('mixed', [
+      { items: [{ _type: 'reference', _ref: 'x' }, 'plain-string'] },
+    ]));
+    const f = schemas[0].fields[0];
+    assert.equal(f.type, 'Object'); // fallback
+    assert.ok(f.items === undefined, 'Object fallback should not carry items');
+    assert.ok(warnings.some(w => /collapsed to Object|Contentful arrays/.test(w.message)));
+  });
+});
+
+// ── Required + presence ─────────────────────────────────────────
+
+describe('inferSchemas — required flag', () => {
+  it('marks a field as required when present in every doc', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { title: 'a' }, { title: 'b' }, { title: 'c' },
+    ]));
+    assert.equal(schemas[0].fields[0].required, true);
+  });
+
+  it('does NOT mark a field as required when missing from some docs', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { title: 'a' }, { title: 'b' }, { other: 'c' },
+    ]));
+    const title = schemas[0].fields.find(f => f.id === 'title')!;
+    assert.notEqual(title.required, true);
+  });
+
+  it('does NOT mark a field as required when value is null in some docs', () => {
+    const { schemas } = inferSchemas(group('post', [
+      { title: 'a' }, { title: null }, { title: 'c' },
+    ] as Array<Record<string, unknown>>));
+    const title = schemas[0].fields.find(f => f.id === 'title')!;
+    assert.notEqual(title.required, true);
+  });
+});
+
+// ── Multi-type orchestration ────────────────────────────────────
+
+describe('inferSchemas — multi-type', () => {
+  it('produces one schema per content type, sorted by id', () => {
+    const samples: DocumentSamplesByType = new Map([
+      ['post', [{ title: 'p' }]],
+      ['author', [{ name: 'a' }]],
+      ['category', [{ name: 'c' }]],
+    ]);
+    const { schemas } = inferSchemas(samples);
+    assert.deepEqual(schemas.map(s => s.id), ['author', 'category', 'post']);
+  });
+
+  it('humanizes content type ids and field ids', () => {
+    const { schemas } = inferSchemas(group('blogPost', [
+      { mainImage: { _type: 'image', asset: { _ref: 'x' } }, publishedAt: '2025-01-01T00:00:00Z' },
+    ]));
+    assert.equal(schemas[0].name, 'Blog Post');
+    const fieldNames = schemas[0].fields.map(f => f.name).sort();
+    assert.deepEqual(fieldNames, ['Main Image', 'Published At']);
+  });
+
+  it('returns empty fields[] for a content type with no docs', () => {
+    const { schemas } = inferSchemas(new Map([['ghost', []]]));
+    assert.equal(schemas[0].fields.length, 0);
+  });
+});
diff --git a/src/sanity/sanity-schema-inference.ts b/src/sanity/sanity-schema-inference.ts
new file mode 100644
index 0000000..8996a09
--- /dev/null
+++ b/src/sanity/sanity-schema-inference.ts
@@ -0,0 +1,301 @@
+/**
+ * Content Model Simulator — Sanity Schema Inference (v0.6.0 M2)
+ *
+ * Given a set of documents grouped by Sanity `_type`, infer a
+ * Contentful-shaped `ContentTypeDefinition` for each: walks each
+ * field across all sampled docs, classifies the value shape, and
+ * maps it to a Contentful field type (Symbol / Text / Integer /
+ * Number / Boolean / Date / Object / Link / Array<...>).
+ *
+ * Zero-dependency. Read-only over the documents.
+ *
+ * Limitations of this cut (deferred to later milestones):
+ * - Multi-locale plugin detection (M7) — `{ en, es, … }` objects are
+ *   typed as plain `Object` for now.
+ * - Portable Text → RichText (M5) — by the time docs reach here,
+ *   the sanity-reader has already collapsed PT to an HTML string, so
+ *   these surface as `Text` here. M5 will move PT detection earlier
+ *   in the pipeline and emit `RichText` instead.
+ * - `linkContentType` validations (later) — refs become `Link/Entry`
+ *   without restricting the target type. The simulator works without
+ *   it; only field-validation strictness suffers.
+ * - `displayField` heuristics — left undefined; the simulator falls
+ *   back to its own priority list.
+ */
+
+import type { ContentTypeDefinition, ContentTypeField, ContentTypeFieldItems } from '../types.js';
+
+// ── Public API ───────────────────────────────────────────────────
+
+export interface InferenceWarning {
+  /** Content type id where the conflict was observed. */
+  contentTypeId: string;
+  /** Field name where the conflict was observed. */
+  fieldId: string;
+  /** Short, machine-stable code: `type-conflict`, `array-object`, `unknown-shape`. */
+  code: 'type-conflict' | 'array-object' | 'unknown-shape' | 'empty-array';
+  /** Human-readable details. */
+  message: string;
+}
+
+export interface InferenceResult {
+  schemas: ContentTypeDefinition[];
+  warnings: InferenceWarning[];
+}
+
+export interface InferenceOptions {
+  /** Threshold (0..1) above which a field present in fewer docs is still considered required. Defaults to 1.0 (must be in every doc). */
+  requiredThreshold?: number;
+  /** Threshold (0..1) above which a shape is considered "dominant" for the field type. Below it, we warn about type conflict. Defaults to 0.66. */
+  dominantThreshold?: number;
+  /** Optional map of `contentTypeId.fieldId` → set of target content type ids,
+   *  produced by `mapDocumentRefs` from real cross-document refs. When present,
+   *  Link Entry fields (and Array<Link Entry> items) get a `linkContentType`
+   *  validation derived from the actually-referenced types. */
+  linkTargets?: Map<string, Set<string>>;
+  /** Optional map of `contentTypeId` → set of field ids that should be flagged
+   *  `localized: true` on the inferred schema. Produced by `detectLocales`. */
+  localizedFields?: Map<string, Set<string>>;
+}
+
+/** Documents grouped by content type (Sanity `_type`). */
+export type DocumentSamplesByType = Map<string, Array<Record<string, unknown> | null | undefined>>;
+
+/**
+ * Build `ContentTypeDefinition`s by inferring field types from real document samples.
+ *
+ * Each entry in `samplesByType` is a list of `Document.data` objects (the
+ * normalized payloads produced by `sanity-reader`) for one content type.
+ */
+export function inferSchemas(
+  samplesByType: DocumentSamplesByType,
+  options: InferenceOptions = {},
+): InferenceResult {
+  const { requiredThreshold = 1.0, dominantThreshold = 0.66, linkTargets, localizedFields } = options;
+  const warnings: InferenceWarning[] = [];
+
+  const schemas: ContentTypeDefinition[] = [...samplesByType.keys()]
+    .sort()
+    .map(typeId => {
+      const samples = (samplesByType.get(typeId) || []).filter(s => s && typeof s === 'object') as Array<Record<string, unknown>>;
+      const fields = inferFieldsForType(typeId, samples, { requiredThreshold, dominantThreshold, linkTargets, localizedFields }, warnings);
+      return {
+        id: typeId,
+        name: humanize(typeId),
+        description: `Pulled from Sanity (${samples.length} document(s)). Field types inferred automatically — review and adjust as needed.`,
+        fields,
+      };
+    });
+
+  return { schemas, warnings };
+}
+
+// ── Field inference ──────────────────────────────────────────────
+
+function inferFieldsForType(
+  contentTypeId: string,
+  samples: Array<Record<string, unknown>>,
+  thresholds: { requiredThreshold: number; dominantThreshold: number; linkTargets?: Map<string, Set<string>>; localizedFields?: Map<string, Set<string>> },
+  warnings: InferenceWarning[],
+): ContentTypeField[] {
+  if (samples.length === 0) return [];
+
+  // Discover all field keys seen across samples, preserving first-seen order.
+  const fieldOrder: string[] = [];
+  const seenFields = new Set<string>();
+  for (const sample of samples) {
+    for (const key of Object.keys(sample)) {
+      if (!seenFields.has(key)) {
+        seenFields.add(key);
+        fieldOrder.push(key);
+      }
+    }
+  }
+
+  return fieldOrder.map(fieldId => {
+    const values = samples.map(s => s[fieldId]).filter(v => v !== undefined && v !== null);
+    const presence = samples.filter(s => s[fieldId] !== undefined && s[fieldId] !== null).length / samples.length;
+
+    const { type, linkType, items, conflict } = inferType(values, fieldId);
+
+    if (conflict) {
+      warnings.push({
+        contentTypeId,
+        fieldId,
+        code: 'type-conflict',
+        message: conflict,
+      });
+    }
+
+    const field: ContentTypeField = {
+      id: fieldId,
+      name: humanize(fieldId),
+      type,
+    };
+    if (linkType) field.linkType = linkType;
+    if (items) field.items = items;
+    if (presence >= thresholds.requiredThreshold && values.length > 0) field.required = true;
+    if (thresholds.localizedFields?.get(contentTypeId)?.has(fieldId)) field.localized = true;
+
+    // Derive `linkContentType` validation from observed refs in the corpus.
+    // Only meaningful for Entry links — Asset links are M6 territory.
+    const targets = thresholds.linkTargets?.get(`${contentTypeId}.${fieldId}`);
+    if (targets && targets.size > 0) {
+      const targetList = [...targets].sort();
+      if (field.type === 'Link' && field.linkType === 'Entry') {
+        field.validations = [{ linkContentType: targetList }];
+      } else if (field.type === 'Array' && field.items?.type === 'Link' && field.items.linkType === 'Entry') {
+        // Build a new items object so we don't mutate the one returned by mapShape.
+        field.items = { ...field.items, validations: [{ linkContentType: targetList }] };
+      }
+    }
+
+    return field;
+  });
+}
+
+// ── Value shape detection ────────────────────────────────────────
+
+/** Internal value classification. Maps 1:n to Contentful field types. */
+type ValueShape =
+  | 'symbol' // string ≤ 256 chars
+  | 'text'   // string > 256 chars
+  | 'datetime' // ISO 8601 string
+  | 'integer'
+  | 'number'
+  | 'boolean'
+  | 'reference' // { _type: 'reference', _ref }
+  | 'image'     // { _type: 'image', asset }
+  | 'richtext'  // { nodeType: 'document', content: [...] }
+  | 'object'    // any other plain object
+  | 'array-ref'
+  | 'array-asset'
+  | 'array-symbol'
+  | 'array-text'
+  | 'array-object'
+  | 'array-empty';
+
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+function detectShape(v: unknown): ValueShape | 'unknown' {
+  if (typeof v === 'string') {
+    if (ISO_DATE_RE.test(v)) return 'datetime';
+    return v.length > 256 ? 'text' : 'symbol';
+  }
+  if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
+  if (typeof v === 'boolean') return 'boolean';
+  if (Array.isArray(v)) {
+    if (v.length === 0) return 'array-empty';
+    const inner = v.map(detectShape).filter(s => s !== 'unknown');
+    if (inner.length === 0) return 'array-object';
+    if (inner.every(s => s === 'reference')) return 'array-ref';
+    if (inner.every(s => s === 'image')) return 'array-asset';
+    if (inner.every(s => s === 'symbol')) return 'array-symbol';
+    if (inner.every(s => s === 'text' || s === 'symbol')) return 'array-text';
+    return 'array-object';
+  }
+  if (v && typeof v === 'object') {
+    const obj = v as Record<string, unknown>;
+    // Sanity refs / images (pre-mapping)
+    if (obj._type === 'reference' && typeof obj._ref === 'string') return 'reference';
+    if (obj._type === 'image' && obj.asset && typeof obj.asset === 'object') return 'image';
+    // Contentful Link sys shape (post-mapping by sanity-ref-mapper / sanity-asset-mapper)
+    const sys = obj.sys as Record<string, unknown> | undefined;
+    if (sys && sys.type === 'Link' && sys.linkType === 'Entry') return 'reference';
+    if (sys && sys.type === 'Link' && sys.linkType === 'Asset') return 'image';
+    // Contentful RichText document
+    if (obj.nodeType === 'document' && Array.isArray(obj.content)) return 'richtext';
+    return 'object';
+  }
+  return 'unknown';
+}
+
+function inferType(
+  values: unknown[],
+  fieldId: string,
+): { type: ContentTypeField['type']; linkType?: ContentTypeField['linkType']; items?: ContentTypeFieldItems; conflict?: string } {
+  if (values.length === 0) {
+    // No non-null values observed; fall back to Symbol (cheapest type).
+    return { type: 'Symbol' };
+  }
+
+  const shapes = values.map(detectShape);
+  const counts = new Map<ValueShape | 'unknown', number>();
+  for (const s of shapes) counts.set(s, (counts.get(s) || 0) + 1);
+
+  // Pick the most common shape, breaking ties by an order that prefers
+  // richer types (Text over Symbol, Number over Integer) — this avoids
+  // demoting a field when one value happens to be short or integer.
+  const ranked = [...counts.entries()].sort(([a, ca], [b, cb]) => {
+    if (ca !== cb) return cb - ca;
+    return shapeBias(a) - shapeBias(b);
+  });
+
+  const [dominantShape] = ranked[0];
+  const dominantCount = ranked[0][1];
+  const dominanceRatio = dominantCount / shapes.length;
+
+  const conflict = ranked.length > 1
+    ? `Field "${fieldId}" has mixed value shapes (${ranked.map(([s, c]) => `${s}:${c}`).join(', ')}). Inferred as ${dominantShape} based on majority (${Math.round(dominanceRatio * 100)}%).`
+    : undefined;
+
+  return mapShape(dominantShape as ValueShape | 'unknown', conflict);
+}
+
+/** Tie-break ranking — lower is preferred when frequencies tie. */
+function shapeBias(s: ValueShape | 'unknown'): number {
+  const order: Array<ValueShape | 'unknown'> = [
+    'datetime', 'number', 'integer', 'boolean', 'text', 'symbol',
+    'reference', 'image', 'richtext',
+    'array-ref', 'array-asset', 'array-text', 'array-symbol', 'array-object', 'array-empty',
+    'object', 'unknown',
+  ];
+  const idx = order.indexOf(s);
+  return idx < 0 ? 999 : idx;
+}
+
+function mapShape(
+  shape: ValueShape | 'unknown',
+  conflict?: string,
+): { type: ContentTypeField['type']; linkType?: ContentTypeField['linkType']; items?: ContentTypeFieldItems; conflict?: string } {
+  switch (shape) {
+    case 'symbol': return { type: 'Symbol', conflict };
+    case 'text': return { type: 'Text', conflict };
+    case 'datetime': return { type: 'Date', conflict };
+    case 'integer': return { type: 'Integer', conflict };
+    case 'number': return { type: 'Number', conflict };
+    case 'boolean': return { type: 'Boolean', conflict };
+    case 'reference': return { type: 'Link', linkType: 'Entry', conflict };
+    case 'image': return { type: 'Link', linkType: 'Asset', conflict };
+    case 'richtext': return { type: 'RichText', conflict };
+    case 'object': return { type: 'Object', conflict };
+    case 'array-ref': return { type: 'Array', items: { type: 'Link', linkType: 'Entry' }, conflict };
+    case 'array-asset': return { type: 'Array', items: { type: 'Link', linkType: 'Asset' }, conflict };
+    case 'array-symbol': return { type: 'Array', items: { type: 'Symbol' }, conflict };
+    case 'array-text':  return { type: 'Array', items: { type: 'Symbol' }, conflict };
+    case 'array-empty': return { type: 'Array', items: { type: 'Symbol' }, conflict };
+    case 'array-object': {
+      // Contentful arrays can only hold Symbol or Link items. Fall back
+      // to plain `Object` (the whole array becomes one Object value),
+      // and surface a warning so the user knows to split or restructure.
+      const note = (conflict ? conflict + ' ' : '') + 'Contentful arrays only support Symbol/Link items — collapsed to Object.';
+      return { type: 'Object', conflict: note };
+    }
+    case 'unknown':
+    default:
+      return { type: 'Object', conflict: (conflict ? conflict + ' ' : '') + 'Unknown value shape — fell back to Object.' };
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+/** Convert `camelCase` / `snake_case` id → `"Title Case"` display name. */
+function humanize(id: string): string {
+  return id
+    .replace(/[_-]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .split(/\s+/)
+    .filter(Boolean)
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}