diff --git a/.changeset/notion-export-cleanup.md b/.changeset/notion-export-cleanup.md
new file mode 100644
index 000000000..445f1bd3c
--- /dev/null
+++ b/.changeset/notion-export-cleanup.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Add `ok migrate notion [dir]` to clean up a Notion "Markdown & CSV" export in place. It normalizes internal links so they both render and resolve (decodes `%20`, handles targets with parentheses, and angle-wraps targets containing spaces), converts `<aside>` callouts to `> [!note]`, lifts database row properties into YAML frontmatter, extracts inline base64 images to files, and renders each database CSV as a markdown table (keeping the per-row pages). Dry-run by default; pass `--apply` to write. Every transform is idempotent, and the command refuses non-Notion directories unless `--force`.
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index f6ded2438..b961b3127 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -458,6 +458,50 @@ jobs:
             echo "::warning::Slack announcement failed for ${RELEASE_TAG} (release is published; notification is best-effort)."
           fi
 
+      # Announce STABLE releases to Discord
+      - name: Announce stable release to Discord
+        if: success() && steps.channel.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}
+          VERSION: ${{ steps.channel.outputs.version }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${DISCORD_WEBHOOK_URL:-}" ]]; then
+            echo "::notice::DISCORD_WEBHOOK_URL not set — skipping Discord announcement for ${RELEASE_TAG}."
+            exit 0
+          fi
+          RELEASE_URL="https://github.com/${GITHUB_REPOSITORY}/releases/tag/${RELEASE_TAG}"
+          NOTES="$(gh release view "$RELEASE_TAG" --json body --jq '.body' 2>/dev/null || true)"
+          NOTES_LIMIT=3500
+          if [[ "${#NOTES}" -gt "$NOTES_LIMIT" ]]; then
+            NOTES="${NOTES:0:$NOTES_LIMIT}…"
+          fi
+          payload="$(jq -n \
+            --arg version "$VERSION" \
+            --arg release_url "$RELEASE_URL" \
+            --arg notes "$NOTES" \
+            '{
+              username: "OpenKnowledge",
+              allowed_mentions: { parse: [] },
+              content: ("🎉 OpenKnowledge \($version) released — " + $release_url),
+              embeds: [
+                { title: ("OpenKnowledge \($version) released"),
+                  url: $release_url,
+                  color: 3638527,
+                  description: (
+                    (if ($notes | length) > 0 then ($notes + "\n\n") else "" end)
+                    + "[Release notes & downloads](\($release_url))"
+                  ) }
+              ]
+            }')"
+          if curl -sS --fail -X POST -H 'Content-Type: application/json' --data "$payload" "$DISCORD_WEBHOOK_URL"; then
+            echo "Posted stable-release announcement for ${RELEASE_TAG} to Discord."
+          else
+            echo "::warning::Discord announcement failed for ${RELEASE_TAG} (release is published; notification is best-effort)."
+          fi
+
       # Lightweight discoverability for stuck-draft state when the promote
       # step (or the build/upload step before it) fails. NOT a substitute
       # for the full paging-design observability deferred in the PR body —
diff --git a/docs/content/integrations/openclaw.mdx b/docs/content/integrations/openclaw.mdx
index 3828602a2..6ac3131b6 100644
--- a/docs/content/integrations/openclaw.mdx
+++ b/docs/content/integrations/openclaw.mdx
@@ -1,6 +1,7 @@
 ---
 title: OpenClaw
 description: Use OpenKnowledge with OpenClaw agents over MCP.
+icon: custom/OpenClaw
 ---
 
 OpenClaw is an agent gateway: it runs agents that connect to MCP servers. Register OpenKnowledge as one of those servers and every agent OpenClaw runs can read, search, and write your knowledge base through OK's tools — with full attribution, link-awareness, conflict-awareness, and a live browser preview. Inside an OK project, agents work markdown through those tools rather than native file access, so every edit stays attributed and previewable.
diff --git a/docs/content/migrate/notion.mdx b/docs/content/migrate/notion.mdx
index 90f8c8a8a..0541bba7a 100644
--- a/docs/content/migrate/notion.mdx
+++ b/docs/content/migrate/notion.mdx
@@ -6,6 +6,18 @@ icon: LuFileInput
 
 This guide will cover exporting your Notion workspace to markdown files so that you can access them from OpenKnowledge. There are several key differences between OpenKnowledge and Notion that make this export incomplete and those will be covered here.
 
+## Install OpenKnowledge
+
+Download the latest version of the OpenKnowledge desktop app for macOS.
+
+<DownloadButton label="Download for macOS" />
+
+and install the [ok CLI](/docs/reference/cli):
+
+```bash
+npm install -g @inkeep/open-knowledge
+```
+
 ## Export your workspace from Notion
 
 1. In Notion, click on your workspace in the top left and go to **Settings**.
@@ -13,6 +25,35 @@ This guide will cover exporting your Notion workspace to markdown files so that
 3. Set **Export format** to **Markdown & CSV** and leave all the default settings.
 4. Download and **unzip** the export folder and move it to your desired location.
 
+## Clean up the export with `ok migrate notion`
+
+The [ok CLI](/docs/reference/cli) ships a cleanup command that resolves format issues with the exported content. By default, the command prints what it would change and writes nothing until you pass `--apply`.
+
+```bash
+# Preview what would change (writes nothing)
+ok migrate notion /path/to/unzipped-export
+
+# Apply the changes
+ok migrate notion /path/to/unzipped-export --apply
+```
+
+Every transform is **idempotent**, so re-running is safe. See the tables below for a full list of differences between the Notion export and what OpenKnowledge supports.
+
+**Options:**
+
+| Flag | Effect |
+| --- | --- |
+| `--apply` | Write the changes (default is a dry-run preview). |
+| `--strip-base64` | Delete inline base64 images instead of extracting them to files. |
+| `--remove-csv` | Delete each `_all.csv` once its table page exists (destructive). |
+| `--only <list>` / `--skip <list>` | Run or skip specific transforms: `links`, `frontmatter`, `callouts`, `images`, `tables`. |
+| `--force` | Run even if the folder isn't detected as a Notion export. |
+| `--json` | Print a machine-readable report. |
+
+<Callout type="info">
+  The command refuses to touch a folder that doesn't look like a Notion export unless you pass `--force`.
+</Callout>
+
 ## Open the export in OpenKnowledge
 
 ### macOS Desktop app
@@ -21,7 +62,7 @@ Open OpenKnowledge, choose **Open folder on disk**, select the unzipped export f
 
 ### Linux, Windows, Intel Mac
 
-Install the [ok CLI](/docs/reference/cli), `cd` into the unzipped folder, and run `ok init && ok start --open`.
+`cd` into the unzipped folder and run `ok init && ok start --open`.
 
 ## What exports cleanly
 
@@ -35,31 +76,21 @@ Install the [ok CLI](/docs/reference/cli), `cd` into the unzipped folder, and ru
 
 ## Where the two differ
 
-A number of Notion features don't survive the Markdown & CSV export, or land as plain text.
-
-| Notion feature | What happens |
-| --- | --- |
-| **Databases** (tables, boards, calendars, galleries, timelines) | Each exports as a stub page, a `<name>_all.csv` of the whole table, and a folder holding one markdown file per row. The per-row pages are first-class docs, but there is no support for viewing complete CSV tables. |
-| **Relations, rollups, formulas** | Not represented in the Markdown & CSV export. |
-| **Database row properties** | Exported as plain `Key: Value` lines under the page title, not YAML frontmatter. |
-| **Callouts** | Exported as raw `<aside>` HTML. The content is preserved, but it isn't converted to OpenKnowledge's native callout (`> [!note]`), so it doesn't pick up callout styling. |
-| **Toggles and toggle headings** | Nested content is preserved, but the collapsible toggle wrapper is lost. |
-| **Synced blocks** | Written out as ordinary content wherever they appear; the link between copies is gone. |
-| **Web bookmarks and embeds** (Figma, video, PDF, etc.) | Converted to plain links. The rich preview card or inline embed is gone. Uploaded files download alongside the page. |
-| **Links between pages** | Notion percent-encodes every link target (every exported filename ends in ` <id>`). Fixable in bulk after import by decoding `%20` and trimming the trailing ` <id>`. |
-| **Pasted or inline images** | Some images export inline as base64 `data:` URIs instead of downloaded files. They don't render and add very large lines to the file. Downloaded `![alt](file.png)` images are unaffected. |
-| **Page icons and cover images** | Not exported. |
-| **Comments, page history, and backlinks** | Not included in the export. |
-
-## Clean up after import (optional)
-
-Most of the rough edges above are mechanical to fix, and the AI agent connected to your project can do it in bulk through OpenKnowledge's [MCP tools](/docs/reference/mcp). Paste any of these prompts to your agent:
-
-- **Decode internal links.** _"In every markdown file, decode `%20` and other percent-escapes in relative `.md` link targets so the links resolve."_ Do this first so the next step can rewrite links.
-- **Drop the Notion ID from filenames.** _"Rename every page to remove the trailing ` <32-character hex id>` from its filename, and verify the links that point to it."_
-- **Promote row properties to frontmatter.** _"On pages exported from databases, turn the `Key: Value` lines under the title into a YAML frontmatter block."_ They then show up in the [Properties panel](/docs/features/editor#properties).
-- **Convert callouts.** _"Replace each `<aside>…</aside>` block with an OpenKnowledge callout (`> [!note]`)."_
-- **Remove inline base64 images.** _"Find `[](data:image/...;base64,...)` blobs and remove them — they don't render and bloat the file."_
+A number of Notion features don't survive the Markdown & CSV export, or land as plain text. Many can be fixed by the [`ok migrate notion <folder-path>`](#clean-up-the-export-with-ok-migrate-notion) command.
+
+| Notion feature | Exported result | Fixed by CLI migration command |
+| --- | --- | --- |
+| **Databases** (tables, boards, calendars, galleries, timelines) | Each database exports as a `<name>_all.csv` file and a folder holding one markdown file per row. Full-page databases also get a stub page. | ✅ Creates a Markdown table page for every CSV. The `.csv` files are not deleted unless you pass `--remove-csv`. |
+| **Database row properties** | Exported as plain `Key: Value` lines under the page title, not YAML frontmatter. | ✅ Lifted into YAML frontmatter so they show in the [Properties panel](/docs/features/editor#properties). |
+| **Callouts** | Exported as raw `<aside>` HTML, so they don't pick up OpenKnowledge's callout styling. | ✅ Converted to native `> [!note]` callouts. |
+| **Links between pages** | Link targets are percent-encoded, and once decoded contain spaces. | ✅ Decoded and angle-wrapped so they render and resolve. |
+| **Pasted or inline images** | Some images export inline as un-rendered base64 `data:` URIs instead of files. | ✅ Extracted to image files (or dropped with `--strip-base64`). |
+| **Relations, rollups, formulas** | Not represented in the Markdown & CSV export. | — |
+| **Toggles and toggle headings** | Nested content is preserved, but the collapsible toggle wrapper is lost. | — |
+| **Synced blocks** | Written out as ordinary content wherever they appear; the link between copies is gone. | — |
+| **Web bookmarks and embeds** (Figma, video, PDF, etc.) | Converted to plain links. The rich preview card or inline embed is gone. Uploaded files download alongside the page. | — |
+| **Page icons and cover images** | Not exported. | — |
+| **Comments, page history, and backlinks** | Not included in the export. | — |
 
 ## See also
 
diff --git a/docs/src/components/icons/brand.ts b/docs/src/components/icons/brand.ts
index 62ba24211..a4e670c88 100644
--- a/docs/src/components/icons/brand.ts
+++ b/docs/src/components/icons/brand.ts
@@ -5,6 +5,7 @@ import { CursorIcon } from './cursor';
 import { GitHubIcon } from './github';
 import { McpIcon } from './mcp';
 import { ObsidianIcon } from './obsidian';
+import { OpenClawIcon } from './openclaw';
 import { OpenCodeIcon } from './opencode';
 
 export const brandIcons = {
@@ -12,6 +13,7 @@ export const brandIcons = {
   Cursor: CursorIcon,
   Codex: CodexIcon,
   OpenCode: OpenCodeIcon,
+  OpenClaw: OpenClawIcon,
   GitHub: GitHubIcon,
   Obsidian: ObsidianIcon,
   MCP: McpIcon,
diff --git a/docs/src/components/icons/openclaw.tsx b/docs/src/components/icons/openclaw.tsx
new file mode 100644
index 000000000..93a26d067
--- /dev/null
+++ b/docs/src/components/icons/openclaw.tsx
@@ -0,0 +1,46 @@
+import type { SVGProps } from 'react';
+
+export function OpenClawIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      role="img"
+      aria-label="OpenClaw icon"
+      xmlns="http://www.w3.org/2000/svg"
+      width={24}
+      height={24}
+      fill="none"
+      viewBox="0 0 120 120"
+      {...props}
+    >
+      <title>OpenClaw icon</title>
+      <mask id="openclaw-eyes" maskUnits="userSpaceOnUse" x={0} y={0} width={120} height={120}>
+        <rect width={120} height={120} fill="white" />
+        <circle cx={45} cy={35} r={6} fill="black" />
+        <circle cx={75} cy={35} r={6} fill="black" />
+      </mask>
+      <g fill="currentColor" mask="url(#openclaw-eyes)">
+        {/* body */}
+        <path d="M60 10 C30 10 15 35 15 55 C15 75 30 95 45 100 L45 110 L55 110 L55 100 C55 100 60 102 65 100 L65 110 L75 110 L75 100 C90 95 105 75 105 55 C105 35 90 10 60 10Z" />
+        {/* left claw */}
+        <path d="M20 45 C5 40 0 50 5 60 C10 70 20 65 25 55 C28 48 25 45 20 45Z" />
+        {/* right claw */}
+        <path d="M100 45 C115 40 120 50 115 60 C110 70 100 65 95 55 C92 48 95 45 100 45Z" />
+      </g>
+      {/* antennae */}
+      <path
+        d="M45 15 Q35 5 30 8"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={3}
+        strokeLinecap="round"
+      />
+      <path
+        d="M75 15 Q85 5 90 8"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={3}
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index ec48e1e12..126b4b71b 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -23,6 +23,7 @@ import { diagnoseCommand } from './commands/diagnose.ts';
 import { embeddingsCommand } from './commands/embeddings/index.ts';
 import { initCommand } from './commands/init.ts';
 import { mcpCommand } from './commands/mcp.ts';
+import { migrateCommand } from './commands/migrate.ts';
 import { openCommand } from './commands/open.ts';
 import { previewCommand } from './commands/preview.ts';
 import { psCommand } from './commands/ps.ts';
@@ -128,6 +129,8 @@ program.addCommand(initCommand());
 
 program.addCommand(seedCommand());
 
+program.addCommand(migrateCommand());
+
 program.addCommand(coworkCommand(), { hidden: true });
 
 program.addCommand(repairSkillsCommand());
diff --git a/packages/cli/src/commands/migrate.test.ts b/packages/cli/src/commands/migrate.test.ts
new file mode 100644
index 000000000..755ea0d2f
--- /dev/null
+++ b/packages/cli/src/commands/migrate.test.ts
@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { makeTree } from './migrate/notion/mktree.test-helper.ts';
+import { migrateCommand } from './migrate.ts';
+
+const ID = '30545f35b5ad80a38049d283dae66763';
+const R1 = '11111111111111111111111111111111';
+const R2 = '22222222222222222222222222222222';
+
+async function run(args: string[]): Promise<{ code: number; stdout: string }> {
+  process.exitCode = 0;
+  const originalLog = console.log;
+  const originalErr = console.error;
+  let stdout = '';
+  console.log = (msg?: unknown) => {
+    stdout += `${String(msg)}\n`;
+  };
+  console.error = () => {};
+  try {
+    await migrateCommand().parseAsync(['notion', ...args], { from: 'user' });
+  } finally {
+    console.log = originalLog;
+    console.error = originalErr;
+  }
+  const code = process.exitCode ?? 0;
+  process.exitCode = 0; // do not leak into the test runner's own exit
+  return { code, stdout };
+}
+
+afterEach(() => {
+  process.exitCode = 0;
+});
+
+describe('ok migrate notion — exit codes', () => {
+  test('exit 2 for an unknown --only transform', async () => {
+    const root = makeTree({ 'page.md': '# P\n' });
+    expect((await run([root, '--only', 'bogus'])).code).toBe(2);
+  });
+
+  test('exit 2 for a directory that is not a Notion export', async () => {
+    const root = makeTree({ 'notes.md': '# Notes\n\nPlain.\n' });
+    expect((await run([root])).code).toBe(2);
+  });
+
+  test('exit 2 with a machine-readable refusal on --json', async () => {
+    const root = makeTree({ 'notes.md': '# Notes\n' });
+    const { code, stdout } = await run([root, '--json']);
+    expect(code).toBe(2);
+    expect(JSON.parse(stdout)).toMatchObject({ refused: true, reason: 'not-a-notion-export' });
+  });
+
+  test('exit 1 when there is nothing to do', async () => {
+    const root = makeTree({ [`Clean ${ID}.md`]: '# Clean\n\nNo links here.\n' });
+    expect((await run([root])).code).toBe(1);
+  });
+
+  test('exit 0 for a dry-run that has changes to preview', async () => {
+    const root = makeTree({ [`Home ${ID}.md`]: '# Home\n\n[x](Foo%20Bar.md)\n' });
+    expect((await run([root])).code).toBe(0);
+  });
+
+  test('exit 3 when --apply completes with ambiguous title links', async () => {
+    const root = makeTree({
+      [`DB ${ID}_all.csv`]: 'Title,X\nNotes,1\nNotes,2\n',
+      [`DB/Notes ${R1}.md`]: '# Notes\n',
+      [`DB/Notes ${R2}.md`]: '# Notes\n',
+    });
+    expect((await run([root, '--apply'])).code).toBe(3);
+  });
+
+  test('exit 3 when --apply produces a wide table (>15 columns)', async () => {
+    const header = Array.from({ length: 16 }, (_, i) => `C${i}`).join(',');
+    const row = Array.from({ length: 16 }, (_, i) => `v${i}`).join(',');
+    const root = makeTree({ [`DB ${ID}_all.csv`]: `${header}\n${row}\n` });
+    expect((await run([root, '--apply'])).code).toBe(3);
+  });
+});
diff --git a/packages/cli/src/commands/migrate.ts b/packages/cli/src/commands/migrate.ts
new file mode 100644
index 000000000..1ff7318e7
--- /dev/null
+++ b/packages/cli/src/commands/migrate.ts
@@ -0,0 +1,122 @@
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import { ALL_TRANSFORMS, applyPlan, buildPlan, type TransformId } from './migrate/notion/plan.ts';
+import { formatReport, formatReportJson } from './migrate/notion/report.ts';
+
+function parseTransformIds(csv: string): TransformId[] {
+  const valid = new Set<string>(ALL_TRANSFORMS);
+  return csv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => {
+      if (!valid.has(s)) {
+        throw new Error(`Unknown transform "${s}". Valid transforms: ${ALL_TRANSFORMS.join(', ')}`);
+      }
+      return s as TransformId;
+    });
+}
+
+function resolveSelected(only?: string, skip?: string): Set<TransformId> {
+  let selected = new Set<TransformId>(ALL_TRANSFORMS);
+  if (only) selected = new Set(parseTransformIds(only));
+  if (skip) for (const id of parseTransformIds(skip)) selected.delete(id);
+  return selected;
+}
+
+interface NotionOptions {
+  apply?: boolean;
+  stripBase64?: boolean;
+  removeCsv?: boolean;
+  only?: string;
+  skip?: string;
+  force?: boolean;
+  json?: boolean;
+}
+
+export function migrateCommand(): Command {
+  const migrate = new Command('migrate').description(
+    'Migrate content from other tools into Open Knowledge',
+  );
+
+  migrate
+    .command('notion [dir]')
+    .description('Clean up a Notion "Markdown & CSV" export in place (dry-run unless --apply)')
+    .option('--apply', 'write changes to disk (default: dry-run preview)')
+    .option('--strip-base64', 'delete inline base64 images instead of extracting them to files')
+    .option('--remove-csv', 'delete each "_all.csv" once its table page exists (destructive)')
+    .option(
+      '--only <transforms>',
+      'run only these transforms (comma-separated: links,frontmatter,callouts,images,tables)',
+    )
+    .option('--skip <transforms>', 'skip these transforms (comma-separated)')
+    .option('--force', 'run even if the directory is not detected as a Notion export')
+    .option('--json', 'print a machine-readable JSON report')
+    .action((dir: string | undefined, options: NotionOptions) => {
+      const target = resolve(dir ?? process.cwd());
+
+      let selected: Set<TransformId>;
+      try {
+        selected = resolveSelected(options.only, options.skip);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 2;
+        return;
+      }
+
+      const plan = buildPlan(target, {
+        selected,
+        stripBase64: options.stripBase64 ?? false,
+        removeCsv: options.removeCsv ?? false,
+        force: options.force ?? false,
+      });
+      const { report } = plan;
+
+      if (!report.isNotionExport && !options.force) {
+        if (options.json) {
+          console.log(
+            JSON.stringify({ refused: true, reason: 'not-a-notion-export', dir: target }, null, 2),
+          );
+        } else {
+          console.error(
+            `Not a Notion export: ${target}\n` +
+              'No id-suffixed pages, "_all.csv", or inline base64 images were found. ' +
+              'Re-run with --force to override.',
+          );
+        }
+        process.exitCode = 2;
+        return;
+      }
+
+      if (options.apply) {
+        try {
+          applyPlan(plan);
+        } catch (err) {
+          console.error(
+            `Failed to apply changes: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exitCode = 4;
+          return;
+        }
+      }
+
+      console.log(
+        options.json
+          ? formatReportJson(report, { applied: options.apply ?? false })
+          : formatReport(report, { applied: options.apply ?? false, dir: target }),
+      );
+
+      const nothingToDo =
+        report.filesChanged === 0 && report.assetsExtracted === 0 && plan.deletions.length === 0;
+      if (nothingToDo) {
+        process.exitCode = 1;
+      } else if (
+        options.apply &&
+        (report.ambiguousTitleLinks > 0 || report.wideTables.length > 0)
+      ) {
+        process.exitCode = 3;
+      }
+    });
+
+  return migrate;
+}
diff --git a/packages/cli/src/commands/migrate/notion/aside-callout.test.ts b/packages/cli/src/commands/migrate/notion/aside-callout.test.ts
new file mode 100644
index 000000000..43d4a26d4
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/aside-callout.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test';
+import { asideToCallout } from './aside-callout.ts';
+
+describe('asideToCallout', () => {
+  test('converts a simple aside to a note callout, dropping the leading emoji', () => {
+    const input = '<aside>\n👋 Welcome to the team!\n</aside>';
+    expect(asideToCallout(input)).toBe('> [!note]\n> Welcome to the team!');
+  });
+
+  test('blockquote-prefixes multi-line content including blank lines and lists', () => {
+    const input = [
+      '<aside>',
+      'Questions? Reach us:',
+      '',
+      '- Slack channel',
+      '- Email',
+      '</aside>',
+    ].join('\n');
+    const expected = [
+      '> [!note]',
+      '> Questions? Reach us:',
+      '>',
+      '> - Slack channel',
+      '> - Email',
+    ].join('\n');
+    expect(asideToCallout(input)).toBe(expected);
+  });
+
+  test('does not emit blank > lines when the first line is only an emoji', () => {
+    const input = '<aside>\n💡\n\nThis deck is based on an article.\n</aside>';
+    expect(asideToCallout(input)).toBe('> [!note]\n> This deck is based on an article.');
+  });
+
+  test('converts multiple asides in one document', () => {
+    const input = '<aside>\nOne\n</aside>\n\ntext\n\n<aside>\nTwo\n</aside>';
+    expect(asideToCallout(input)).toBe('> [!note]\n> One\n\ntext\n\n> [!note]\n> Two');
+  });
+
+  test('is idempotent — no aside tags remain after conversion', () => {
+    const input = '<aside>\n💡 Tip here\n</aside>';
+    const once = asideToCallout(input);
+    expect(asideToCallout(once)).toBe(once);
+    expect(once).not.toContain('<aside>');
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/aside-callout.ts b/packages/cli/src/commands/migrate/notion/aside-callout.ts
new file mode 100644
index 000000000..a916ab67f
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/aside-callout.ts
@@ -0,0 +1,16 @@
+const ASIDE = /<aside>\s*([\s\S]*?)\s*<\/aside>/g;
+const LEADING_EMOJI = /^(?:\p{Extended_Pictographic}️?\s*)+/u;
+
+export function asideToCallout(markdown: string): string {
+  return markdown.replace(ASIDE, (_match, rawInner: string) => {
+    const lines = rawInner.replace(/\r\n/g, '\n').split('\n');
+    while (lines.length > 0 && (lines[0] as string).trim() === '') lines.shift();
+    while (lines.length > 0 && (lines[lines.length - 1] as string).trim() === '') lines.pop();
+    if (lines.length > 0) {
+      lines[0] = (lines[0] as string).replace(LEADING_EMOJI, '');
+      while (lines.length > 0 && (lines[0] as string).trim() === '') lines.shift();
+    }
+    const body = lines.map((line) => (line.trim() === '' ? '>' : `> ${line}`)).join('\n');
+    return body ? `> [!note]\n${body}` : '> [!note]';
+  });
+}
diff --git a/packages/cli/src/commands/migrate/notion/base64-images.test.ts b/packages/cli/src/commands/migrate/notion/base64-images.test.ts
new file mode 100644
index 000000000..dbfb1aa82
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/base64-images.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test';
+import { extractBase64Images } from './base64-images.ts';
+
+const PNG_B64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+
+describe('extractBase64Images', () => {
+  test('extracts an empty-text data-image link into a file and rewrites as an image embed', () => {
+    const input = `Before\n\n[](data:image/png;base64,${PNG_B64})\n\nAfter`;
+    const { markdown, assets } = extractBase64Images(input, 'My Page 2ee45f35b5ad80.md');
+    expect(assets).toHaveLength(1);
+    expect(assets[0]?.filename).toBe('my-page-2ee45f35b5ad80-inline-1.png');
+    expect(assets[0]?.bytes.length).toBeGreaterThan(0);
+    expect(markdown).toContain('![](my-page-2ee45f35b5ad80-inline-1.png)');
+    expect(markdown).not.toContain('data:image');
+  });
+
+  test('numbers multiple blobs deterministically', () => {
+    const input = `![a](data:image/png;base64,${PNG_B64})\n![b](data:image/gif;base64,${PNG_B64})`;
+    const { markdown, assets } = extractBase64Images(input, 'page.md');
+    expect(assets.map((a) => a.filename)).toEqual(['page-inline-1.png', 'page-inline-2.gif']);
+    expect(markdown).toContain('![a](page-inline-1.png)');
+    expect(markdown).toContain('![b](page-inline-2.gif)');
+  });
+
+  test('strip mode removes the blob and writes no asset', () => {
+    const input = `x [](data:image/png;base64,${PNG_B64}) y`;
+    const { markdown, assets } = extractBase64Images(input, 'page.md', { strip: true });
+    expect(assets).toHaveLength(0);
+    expect(markdown).toBe('x  y');
+    expect(markdown).not.toContain('data:image');
+  });
+
+  test('is idempotent — no data: blobs remain after extraction', () => {
+    const input = `[](data:image/png;base64,${PNG_B64})`;
+    const first = extractBase64Images(input, 'page.md');
+    const second = extractBase64Images(first.markdown, 'page.md');
+    expect(second.markdown).toBe(first.markdown);
+    expect(second.assets).toHaveLength(0);
+  });
+
+  test('leaves markdown with no data-image blobs unchanged', () => {
+    const input = '# Title\n\n![real](photo.png)\n';
+    const { markdown, assets } = extractBase64Images(input, 'page.md');
+    expect(markdown).toBe(input);
+    expect(assets).toHaveLength(0);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/base64-images.ts b/packages/cli/src/commands/migrate/notion/base64-images.ts
new file mode 100644
index 000000000..575a94bcb
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/base64-images.ts
@@ -0,0 +1,51 @@
+export interface Base64Result {
+  markdown: string;
+  assets: Array<{ filename: string; bytes: Uint8Array }>;
+}
+
+const DATA_IMAGE = /(!?)\[([^\]]*)\]\(data:image\/([a-z0-9.+-]+);base64,([A-Za-z0-9+/=\s]+?)\)/gi;
+
+const EXT_BY_SUBTYPE: Record<string, string> = {
+  png: 'png',
+  jpeg: 'jpg',
+  jpg: 'jpg',
+  gif: 'gif',
+  webp: 'webp',
+  'svg+xml': 'svg',
+};
+
+function slugify(name: string): string {
+  return (
+    name
+      .replace(/\.(md|mdx)$/i, '')
+      .replace(/[^A-Za-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .toLowerCase() || 'inline'
+  );
+}
+
+export function extractBase64Images(
+  markdown: string,
+  pageName: string,
+  opts: { strip?: boolean } = {},
+): Base64Result {
+  const assets: Base64Result['assets'] = [];
+  const slug = slugify(pageName);
+  let n = 0;
+
+  const out = markdown.replace(
+    DATA_IMAGE,
+    (_match, _bang, alt: string, subtype: string, payload: string) => {
+      if (opts.strip) return '';
+      n += 1;
+      const ext =
+        EXT_BY_SUBTYPE[subtype.toLowerCase()] ?? subtype.toLowerCase().replace(/[^a-z0-9]/g, '');
+      const filename = `${slug}-inline-${n}.${ext}`;
+      const bytes = new Uint8Array(Buffer.from(payload.replace(/\s+/g, ''), 'base64'));
+      assets.push({ filename, bytes });
+      return `![${alt}](${filename})`;
+    },
+  );
+
+  return { markdown: out, assets };
+}
diff --git a/packages/cli/src/commands/migrate/notion/csv.test.ts b/packages/cli/src/commands/migrate/notion/csv.test.ts
new file mode 100644
index 000000000..825456c9a
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/csv.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import { parseCsv } from './csv.ts';
+
+describe('parseCsv', () => {
+  test('parses a simple header + rows', () => {
+    const { header, rows } = parseCsv('a,b,c\n1,2,3\n4,5,6\n');
+    expect(header).toEqual(['a', 'b', 'c']);
+    expect(rows).toEqual([
+      ['1', '2', '3'],
+      ['4', '5', '6'],
+    ]);
+  });
+
+  test('strips a leading UTF-8 BOM from the first field', () => {
+    const { header } = parseCsv('Name,Status\nAlpha,Done\n');
+    expect(header).toEqual(['Name', 'Status']);
+  });
+
+  test('keeps commas inside quoted fields as one cell', () => {
+    const { rows } = parseCsv('a,b\n"x, y, z",2\n');
+    expect(rows).toEqual([['x, y, z', '2']]);
+  });
+
+  test('unescapes doubled quotes inside quoted fields', () => {
+    const { rows } = parseCsv('a\n"she said ""hi"""\n');
+    expect(rows).toEqual([['she said "hi"']]);
+  });
+
+  test('preserves an embedded newline inside a quoted field as one cell', () => {
+    const { header, rows } = parseCsv('a,b\n"line one\nline two",2\n');
+    expect(header).toEqual(['a', 'b']);
+    expect(rows).toEqual([['line one\nline two', '2']]);
+    expect(rows).toHaveLength(1);
+  });
+
+  test('handles CRLF line endings', () => {
+    const { header, rows } = parseCsv('a,b\r\n1,2\r\n');
+    expect(header).toEqual(['a', 'b']);
+    expect(rows).toEqual([['1', '2']]);
+  });
+
+  test('returns empty rows for a header-only CSV without throwing', () => {
+    const { header, rows } = parseCsv('Name,Status,Owner\n');
+    expect(header).toEqual(['Name', 'Status', 'Owner']);
+    expect(rows).toEqual([]);
+  });
+
+  test('handles a final row with no trailing newline', () => {
+    const { rows } = parseCsv('a,b\n1,2');
+    expect(rows).toEqual([['1', '2']]);
+  });
+
+  test('preserves trailing empty fields', () => {
+    const { rows } = parseCsv('a,b,c\n1,,\n');
+    expect(rows).toEqual([['1', '', '']]);
+  });
+
+  test('empty input yields empty header and rows', () => {
+    const { header, rows } = parseCsv('');
+    expect(header).toEqual([]);
+    expect(rows).toEqual([]);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/csv.ts b/packages/cli/src/commands/migrate/notion/csv.ts
new file mode 100644
index 000000000..444c8bb83
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/csv.ts
@@ -0,0 +1,64 @@
+export interface ParsedCsv {
+  header: string[];
+  rows: string[][];
+}
+
+export function parseCsv(input: string): ParsedCsv {
+  const text = input.charCodeAt(0) === 0xfeff ? input.slice(1) : input;
+
+  const records: string[][] = [];
+  let field = '';
+  let record: string[] = [];
+  let inQuotes = false;
+  let started = false;
+
+  const endField = () => {
+    record.push(field);
+    field = '';
+  };
+  const endRecord = () => {
+    endField();
+    records.push(record);
+    record = [];
+    started = false;
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += c;
+      }
+      started = true;
+      continue;
+    }
+
+    if (c === '"') {
+      inQuotes = true;
+      started = true;
+    } else if (c === ',') {
+      endField();
+      started = true;
+    } else if (c === '\n') {
+      endRecord();
+    } else if (c === '\r') {
+      if (text[i + 1] === '\n') i++;
+      endRecord();
+    } else {
+      field += c;
+      started = true;
+    }
+  }
+  if (started || field !== '') endRecord();
+
+  const header = records.length > 0 ? (records[0] as string[]) : [];
+  const rows = records.slice(1);
+  return { header, rows };
+}
diff --git a/packages/cli/src/commands/migrate/notion/databases.ts b/packages/cli/src/commands/migrate/notion/databases.ts
new file mode 100644
index 000000000..a6be76e1d
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/databases.ts
@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { basename, sep } from 'node:path';
+import { parseCsv } from './csv.ts';
+import { buildIndex } from './normalized-index.ts';
+
+const TRAILING_ID = /\s+[0-9a-f]{32}$/i;
+const MD = /\.mdx?$/i;
+
+export interface DatabaseInfo {
+  csvPath: string;
+  stubPath: string | null;
+  stubTargetPath: string;
+  folderPath: string;
+  propertyKeys: Set<string>;
+  csvText: string;
+  rowFiles: string[];
+  folderIndex: Map<string, string[]>;
+  fallbackTitle: string;
+}
+
+export function detectDatabases(
+  files: readonly string[],
+  opts: { onUnreadable?: (path: string) => void } = {},
+): DatabaseInfo[] {
+  const fileSet = new Set(files);
+  const out: DatabaseInfo[] = [];
+
+  for (const csvPath of files) {
+    if (!csvPath.endsWith('_all.csv')) continue;
+    const base = csvPath.slice(0, -'_all.csv'.length); // `.../Name <id>`
+    const stubPath = fileSet.has(`${base}.md`)
+      ? `${base}.md`
+      : fileSet.has(`${base}.mdx`)
+        ? `${base}.mdx`
+        : null;
+    const folderPath = base.replace(TRAILING_ID, ''); // `.../Name`
+
+    let csvText = '';
+    try {
+      csvText = readFileSync(csvPath, 'utf8');
+    } catch {
+      opts.onUnreadable?.(csvPath);
+    }
+    const header = parseCsv(csvText).header;
+    const propertyKeys = new Set(header.map((h) => h.trim()).filter((h) => h.length > 0));
+
+    const rowFiles = files.filter(
+      (f) => f !== stubPath && MD.test(f) && f.startsWith(`${folderPath}${sep}`),
+    );
+
+    out.push({
+      csvPath,
+      stubPath,
+      stubTargetPath: `${base}.md`,
+      folderPath,
+      propertyKeys,
+      csvText,
+      rowFiles,
+      folderIndex: buildIndex(rowFiles),
+      fallbackTitle: basename(folderPath),
+    });
+  }
+
+  return out;
+}
diff --git a/packages/cli/src/commands/migrate/notion/decode-links.test.ts b/packages/cli/src/commands/migrate/notion/decode-links.test.ts
new file mode 100644
index 000000000..467e9429a
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/decode-links.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test';
+import { decodeLinks } from './decode-links.ts';
+
+const ID = '30545f35b5ad80a38049d283dae66763';
+
+describe('decodeLinks', () => {
+  test('decodes an encoded internal .md link and angle-wraps the spaced target', () => {
+    const input = `See [Create a Role](Zendesk%20Integration%20${ID}.md) now.`;
+    expect(decodeLinks(input)).toBe(`See [Create a Role](<Zendesk Integration ${ID}.md>) now.`);
+  });
+
+  test('decodes a link target that contains literal parentheses (paren-depth aware)', () => {
+    const input = `[Voice](Teamspace Home/Voice of Customer Analysis EDB (EnterpriseDB)%202f04.md)`;
+    expect(decodeLinks(input)).toBe(
+      `[Voice](<Teamspace Home/Voice of Customer Analysis EDB (EnterpriseDB) 2f04.md>)`,
+    );
+  });
+
+  test('decodes a target that both starts with and contains parentheses', () => {
+    const input = `[GtM]((Primer x Inkeep)%20GtM/GtM%20Newsletter%202e34.md)`;
+    expect(decodeLinks(input)).toBe(`[GtM](<(Primer x Inkeep) GtM/GtM Newsletter 2e34.md>)`);
+  });
+
+  test('angle-wraps an already-decoded target that has literal spaces (so it renders)', () => {
+    const input = '[Customer Snapshot](Netcraft x Inkeep/Customer Snapshot 29945_all.csv)';
+    expect(decodeLinks(input)).toBe(
+      '[Customer Snapshot](<Netcraft x Inkeep/Customer Snapshot 29945_all.csv>)',
+    );
+  });
+
+  test('leaves a space-free target unwrapped', () => {
+    expect(decodeLinks('[x](simple.md)')).toBe('[x](simple.md)');
+  });
+
+  test('decodes and wraps image targets too', () => {
+    expect(decodeLinks('![shot](Some%20Page/Screenshot%202026.png)')).toBe(
+      '![shot](<Some Page/Screenshot 2026.png>)',
+    );
+  });
+
+  test('leaves external URLs untouched', () => {
+    const input = '[api](https://api.example.com/run%20now)';
+    expect(decodeLinks(input)).toBe(input);
+  });
+
+  test('leaves bare anchors untouched', () => {
+    expect(decodeLinks('[top](#some%20heading)')).toBe('[top](#some%20heading)');
+  });
+
+  test('does not touch links inside inline code', () => {
+    const input = 'Use `[x](Foo%20Bar.md)` literally.';
+    expect(decodeLinks(input)).toBe(input);
+  });
+
+  test('does not touch links inside fenced code blocks', () => {
+    const input = ['```md', '[x](Foo%20Bar.md)', '```', '[y](Baz%20Qux.md)'].join('\n');
+    const expected = ['```md', '[x](Foo%20Bar.md)', '```', '[y](<Baz Qux.md>)'].join('\n');
+    expect(decodeLinks(input)).toBe(expected);
+  });
+
+  test('is idempotent — a second pass produces identical bytes', () => {
+    const input = `[a](Foo%20Bar%20${ID}.md) and [b](With (Parens)%20x.md)`;
+    const once = decodeLinks(input);
+    expect(decodeLinks(once)).toBe(once);
+  });
+
+  test('does not mis-toggle fence state on a mismatched fence character', () => {
+    const input = [
+      '```',
+      '[x](Foo%20Bar.md)',
+      '~~~',
+      '[y](Baz%20Qux.md)',
+      '```',
+      '[z](Q%20R.md)',
+    ].join('\n');
+    const out = decodeLinks(input);
+    expect(out).toContain('[x](Foo%20Bar.md)'); // inside the block, untouched
+    expect(out).toContain('[y](Baz%20Qux.md)'); // still inside the block, untouched
+    expect(out).toContain('[z](<Q R.md>)'); // after the block, rewritten
+  });
+
+  test('redirects internal _all.csv link targets to the .md table page when enabled', () => {
+    const input = '[Customers](<DB/Customers 29945_all.csv>)';
+    expect(decodeLinks(input, { redirectCsv: true })).toBe('[Customers](<DB/Customers 29945.md>)');
+  });
+
+  test('leaves _all.csv targets alone when redirect is disabled', () => {
+    const input = '[Customers](<DB/Customers 29945_all.csv>)';
+    expect(decodeLinks(input, { redirectCsv: false })).toBe(input);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/decode-links.ts b/packages/cli/src/commands/migrate/notion/decode-links.ts
new file mode 100644
index 000000000..ecd7c6cfe
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/decode-links.ts
@@ -0,0 +1,122 @@
+const EXTERNAL = /^[a-z][a-z0-9+.-]*:/i;
+const FENCE = /^\s*(`{3,}|~{3,})/;
+const CSV_TABLE_TARGET = /_all\.csv(?=$|[#?])/i;
+
+function decodePath(url: string): string {
+  const cut = Math.min(
+    ...[url.indexOf('#'), url.indexOf('?')].filter((i) => i >= 0).concat(url.length),
+  );
+  const path = url.slice(0, cut);
+  const suffix = url.slice(cut);
+  try {
+    return decodeURIComponent(path) + suffix;
+  } catch {
+    return url;
+  }
+}
+
+function rewriteTarget(raw: string, redirectCsv: boolean): string {
+  if (raw.startsWith('<') && raw.endsWith('>')) {
+    const inner = raw.slice(1, -1);
+    if (EXTERNAL.test(inner) || inner.startsWith('//') || inner.startsWith('#')) return raw;
+    let decoded = decodePath(inner);
+    if (redirectCsv) decoded = decoded.replace(CSV_TABLE_TARGET, '.md');
+    return `<${decoded}>`;
+  }
+  if (EXTERNAL.test(raw) || raw.startsWith('//') || raw.startsWith('#')) return raw;
+
+  let decoded = decodePath(raw);
+  if (redirectCsv) decoded = decoded.replace(CSV_TABLE_TARGET, '.md');
+  return /\s/.test(decoded) ? `<${decoded}>` : decoded;
+}
+
+function rewriteTargets(text: string, redirectCsv: boolean): string {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const open = text.indexOf('](', i);
+    if (open === -1) {
+      out += text.slice(i);
+      break;
+    }
+    out += text.slice(i, open + 2); // include `](`
+    const j = open + 2;
+
+    if (text[j] === '<') {
+      const close = text.indexOf('>', j);
+      if (close === -1 || text[close + 1] !== ')') {
+        i = j;
+        continue;
+      }
+      out += `${rewriteTarget(text.slice(j, close + 1), redirectCsv)})`;
+      i = close + 2;
+      continue;
+    }
+
+    let depth = 1;
+    let k = j;
+    for (; k < text.length; k++) {
+      const c = text[k];
+      if (c === '(') depth++;
+      else if (c === ')') {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    if (k >= text.length) {
+      out += text.slice(j);
+      break;
+    }
+    out += `${rewriteTarget(text.slice(j, k), redirectCsv)})`;
+    i = k + 1;
+  }
+  return out;
+}
+
+function rewriteLineOutsideCode(line: string, redirectCsv: boolean): string {
+  let out = '';
+  let i = 0;
+  while (i < line.length) {
+    if (line[i] === '`') {
+      let ticks = 0;
+      while (line[i + ticks] === '`') ticks++;
+      const open = line.slice(i, i + ticks);
+      const closeIdx = line.indexOf(open, i + ticks);
+      if (closeIdx >= 0) {
+        out += line.slice(i, closeIdx + ticks);
+        i = closeIdx + ticks;
+        continue;
+      }
+      out += line.slice(i);
+      break;
+    }
+    const next = line.indexOf('`', i);
+    const end = next === -1 ? line.length : next;
+    out += rewriteTargets(line.slice(i, end), redirectCsv);
+    i = end;
+  }
+  return out;
+}
+
+export interface DecodeLinksOptions {
+  redirectCsv?: boolean;
+}
+
+export function decodeLinks(markdown: string, opts: DecodeLinksOptions = {}): string {
+  const redirectCsv = opts.redirectCsv ?? false;
+  const lines = markdown.split('\n');
+  let fenceChar: '`' | '~' | null = null;
+  for (let n = 0; n < lines.length; n++) {
+    const line = lines[n] as string;
+    const match = line.match(FENCE);
+    if (match) {
+      const ch = (match[1] as string)[0] as '`' | '~';
+      if (fenceChar === null) fenceChar = ch;
+      else if (ch === fenceChar) fenceChar = null;
+      continue;
+    }
+    if (fenceChar !== null) continue;
+    lines[n] = rewriteLineOutsideCode(line, redirectCsv);
+  }
+  return lines.join('\n');
+}
diff --git a/packages/cli/src/commands/migrate/notion/detect.test.ts b/packages/cli/src/commands/migrate/notion/detect.test.ts
new file mode 100644
index 000000000..092071769
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/detect.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+import { isNotionExport } from './detect.ts';
+import { makeTree } from './mktree.test-helper.ts';
+
+const ID = '2a145f35b5ad808e9200ff850d964d8f';
+
+describe('isNotionExport', () => {
+  test('detects an id-suffixed markdown filename', () => {
+    const root = makeTree({ [`Content Plan ${ID}.md`]: '# Content Plan\n' });
+    expect(isNotionExport(root)).toBe(true);
+  });
+
+  test('detects a database _all.csv', () => {
+    const root = makeTree({ [`Content Plan ${ID}_all.csv`]: 'a,b\n1,2\n' });
+    expect(isNotionExport(root)).toBe(true);
+  });
+
+  test('detects an inline base64 image blob', () => {
+    const root = makeTree({ 'page.md': '# P\n\n[](data:image/png;base64,iVBORw0KGgo=)\n' });
+    expect(isNotionExport(root)).toBe(true);
+  });
+
+  test('returns false for an ordinary markdown directory', () => {
+    const root = makeTree({ 'notes.md': '# Notes\n\nJust text.\n', 'readme.md': '# Readme\n' });
+    expect(isNotionExport(root)).toBe(false);
+  });
+
+  test('ignores signals inside dot-directories', () => {
+    const root = makeTree({ [`.ok/cache/x ${ID}.md`]: 'x', 'plain.md': '# plain\n' });
+    expect(isNotionExport(root)).toBe(false);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/detect.ts b/packages/cli/src/commands/migrate/notion/detect.ts
new file mode 100644
index 000000000..e9974c9c4
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/detect.ts
@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { walkFiles } from './fs-walk.ts';
+
+const ID_SUFFIXED_MD = / [0-9a-f]{32}\.mdx?$/i;
+const BASE64_IMAGE = /data:image\/[a-z0-9.+-]+;base64,/i;
+
+export function isNotionExport(dir: string): boolean {
+  const files = walkFiles(dir);
+  for (const f of files) {
+    if (f.endsWith('_all.csv')) return true;
+    if (ID_SUFFIXED_MD.test(f)) return true;
+  }
+  for (const f of files) {
+    if (!/\.mdx?$/i.test(f)) continue;
+    try {
+      if (BASE64_IMAGE.test(readFileSync(f, 'utf8'))) return true;
+    } catch {}
+  }
+  return false;
+}
diff --git a/packages/cli/src/commands/migrate/notion/fs-walk.test.ts b/packages/cli/src/commands/migrate/notion/fs-walk.test.ts
new file mode 100644
index 000000000..0a73a80ec
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/fs-walk.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test';
+import { symlinkSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { walkFiles } from './fs-walk.ts';
+import { makeTree } from './mktree.test-helper.ts';
+
+describe('walkFiles', () => {
+  test('lists files recursively', () => {
+    const root = makeTree({
+      'a.md': 'A',
+      'sub/b.md': 'B',
+      'sub/deep/c.md': 'C',
+    });
+    const names = walkFiles(root)
+      .map((f) => basename(f))
+      .sort();
+    expect(names).toEqual(['a.md', 'b.md', 'c.md']);
+  });
+
+  test('skips dotfiles and dot-directories (.ok, .git)', () => {
+    const root = makeTree({
+      'keep.md': 'K',
+      '.okignore': 'x',
+      '.ok/local/server.lock': 'lock',
+      '.git/HEAD': 'ref',
+    });
+    const names = walkFiles(root).map((f) => basename(f));
+    expect(names).toEqual(['keep.md']);
+  });
+
+  test('returns empty for a missing directory without throwing', () => {
+    expect(walkFiles('/no/such/dir/ok-migrate-xyz')).toEqual([]);
+  });
+
+  test('does not descend into directory symlinks (ancestor link would cycle forever)', () => {
+    const root = makeTree({ 'a.md': 'A', 'sub/b.md': 'B' });
+    symlinkSync(root, join(root, 'sub', 'loop'));
+    const names = walkFiles(root)
+      .map((f) => basename(f))
+      .sort();
+    expect(names).toEqual(['a.md', 'b.md']);
+  });
+
+  test('includes symlinks to files', () => {
+    const root = makeTree({ 'real.md': 'R' });
+    symlinkSync(join(root, 'real.md'), join(root, 'alias.md'));
+    const names = walkFiles(root)
+      .map((f) => basename(f))
+      .sort();
+    expect(names).toEqual(['alias.md', 'real.md']);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/fs-walk.ts b/packages/cli/src/commands/migrate/notion/fs-walk.ts
new file mode 100644
index 000000000..340a033db
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/fs-walk.ts
@@ -0,0 +1,36 @@
+import { lstatSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function walkFiles(root: string): string[] {
+  const out: string[] = [];
+  const stack: string[] = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop() as string;
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (name.startsWith('.')) continue;
+      const full = join(dir, name);
+      let isDir = false;
+      let isFile = false;
+      try {
+        const st = lstatSync(full);
+        if (st.isSymbolicLink()) {
+          isFile = statSync(full).isFile();
+        } else {
+          isDir = st.isDirectory();
+          isFile = st.isFile();
+        }
+      } catch {
+        continue;
+      }
+      if (isDir) stack.push(full);
+      else if (isFile) out.push(full);
+    }
+  }
+  return out;
+}
diff --git a/packages/cli/src/commands/migrate/notion/mktree.test-helper.ts b/packages/cli/src/commands/migrate/notion/mktree.test-helper.ts
new file mode 100644
index 000000000..daa2de6e8
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/mktree.test-helper.ts
@@ -0,0 +1,17 @@
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export function makeTree(files: Record<string, string | Uint8Array>): string {
+  const root = mkdtempSync(join(tmpdir(), 'ok-migrate-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+export function read(root: string, rel: string): string {
+  return readFileSync(join(root, rel), 'utf8');
+}
diff --git a/packages/cli/src/commands/migrate/notion/normalized-index.test.ts b/packages/cli/src/commands/migrate/notion/normalized-index.test.ts
new file mode 100644
index 000000000..6f42bbda1
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/normalized-index.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test';
+import { buildIndex, normalizeKey, resolveKey } from './normalized-index.ts';
+
+const ID = '30545f35b5ad80a38049d283dae66763';
+
+describe('normalizeKey', () => {
+  test('folds an encoded, id-suffixed link target and its spaced filename to the same key', () => {
+    const link = `Zendesk%20Integration%20Content%20Writer%20Agent%20${ID}.md`;
+    const file = `Zendesk Integration Content Writer Agent ${ID}.md`;
+    expect(normalizeKey(link)).toBe(normalizeKey(file));
+    expect(normalizeKey(file)).toBe('zendesk integration content writer agent');
+  });
+
+  test('strips Notion-illegal punctuation kept in titles but not filenames', () => {
+    expect(normalizeKey('What are the perils (today)?')).toBe('what are the perils today');
+  });
+
+  test('matches on the last path segment for relative links', () => {
+    expect(normalizeKey(`../db/Content Plan ${ID}.md`)).toBe('content plan');
+  });
+
+  test('tolerates malformed percent-encoding without throwing', () => {
+    expect(normalizeKey('bad%zzname.md')).toBe('bad%zzname');
+  });
+});
+
+describe('buildIndex + resolveKey', () => {
+  test('resolves an encoded id-suffixed link to its real file', () => {
+    const file = `Foo Bar ${ID}.md`;
+    const index = buildIndex([file, `Other ${ID}.md`]);
+    const res = resolveKey(index, `Foo%20Bar%20${ID}.md`);
+    expect(res).toEqual({ path: file, ambiguous: false });
+  });
+
+  test('reports ambiguity for duplicate titles and never guesses', () => {
+    const a = `dir-a/Notes ${ID}.md`;
+    const b = `dir-b/Notes ${'a'.repeat(32)}.md`;
+    const index = buildIndex([a, b]);
+    const res = resolveKey(index, 'Notes.md');
+    expect(res.path).toBeNull();
+    expect(res.ambiguous).toBe(true);
+  });
+
+  test('returns a null non-ambiguous resolution for a missing target', () => {
+    const index = buildIndex([`Foo ${ID}.md`]);
+    expect(resolveKey(index, 'Nope.md')).toEqual({ path: null, ambiguous: false });
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/normalized-index.ts b/packages/cli/src/commands/migrate/notion/normalized-index.ts
new file mode 100644
index 000000000..b26eadbf1
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/normalized-index.ts
@@ -0,0 +1,40 @@
+const ILLEGAL_PUNCT = /[*"/\\<>:|?()]/g;
+const DOC_EXT = /\.(md|mdx)$/i;
+const TRAILING_ID = /\s+[0-9a-f]{32}$/i;
+
+export function normalizeKey(input: string): string {
+  let v = input.split(/[\\/]/).pop() ?? input;
+  try {
+    v = decodeURIComponent(v);
+  } catch {}
+  v = v.replace(DOC_EXT, '');
+  v = v.replace(TRAILING_ID, '');
+  v = v.replace(ILLEGAL_PUNCT, '');
+  v = v.replace(/\s+/g, ' ').trim().toLowerCase();
+  return v;
+}
+
+export function buildIndex(files: readonly string[]): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+  for (const f of files) {
+    const key = normalizeKey(f);
+    if (!key) continue;
+    const arr = map.get(key);
+    if (arr) arr.push(f);
+    else map.set(key, [f]);
+  }
+  return map;
+}
+
+export interface Resolution {
+  path: string | null;
+  ambiguous: boolean;
+}
+
+export function resolveKey(index: Map<string, string[]>, target: string): Resolution {
+  const key = normalizeKey(target);
+  const hits = key ? index.get(key) : undefined;
+  if (!hits || hits.length === 0) return { path: null, ambiguous: false };
+  if (hits.length > 1) return { path: null, ambiguous: true };
+  return { path: hits[0] as string, ambiguous: false };
+}
diff --git a/packages/cli/src/commands/migrate/notion/plan.test.ts b/packages/cli/src/commands/migrate/notion/plan.test.ts
new file mode 100644
index 000000000..46613d1bc
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/plan.test.ts
@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { walkFiles } from './fs-walk.ts';
+import { makeTree, read } from './mktree.test-helper.ts';
+import { applyPlan, buildPlan } from './plan.ts';
+
+const PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+const ID = '2a145f35b5ad808e9200ff850d964d8f';
+const HOME = '2fb45f35b5ad81ea89410042576b8439';
+const R1 = '11111111111111111111111111111111';
+const R2 = '22222222222222222222222222222222';
+
+function notionExport(): string {
+  return makeTree({
+    [`Home ${HOME}.md`]: [
+      '# Home',
+      '',
+      `See [Content Plan](Content%20Plan%20${ID}.md).`,
+      '',
+      `[](data:image/png;base64,${PNG})`,
+      '',
+      '<aside>',
+      '👋 Welcome!',
+      '</aside>',
+      '',
+    ].join('\n'),
+    [`Content Plan ${ID}.md`]: `# Content Plan\n\n[Content Plan](Content%20Plan%20${ID}_all.csv)\n`,
+    [`Content Plan ${ID}_all.csv`]:
+      'Headline,Status,Note\n"Alpha (v1)",Done,"line1\nline2"\n"Beta",Todo,"a | b"\n',
+    [`Content Plan/Alpha v1 ${R1}.md`]: [
+      '# Alpha (v1)',
+      '',
+      'Status: Done',
+      'Note: line1',
+      '',
+      '## Body',
+      '',
+      'Has a real body.',
+      '',
+    ].join('\n'),
+    [`Content Plan/Beta ${R2}.md`]: '# Beta\n\nStatus: Todo\n',
+  });
+}
+
+function snapshot(root: string): Map<string, Buffer> {
+  const snap = new Map<string, Buffer>();
+  for (const f of walkFiles(root)) snap.set(f.slice(root.length), readFileSync(f));
+  return snap;
+}
+
+describe('buildPlan / applyPlan', () => {
+  test('dry-run reports changes but writes nothing', () => {
+    const root = notionExport();
+    const before = snapshot(root);
+    const { report, changes } = buildPlan(root);
+    expect(report.isNotionExport).toBe(true);
+    expect(changes.length).toBeGreaterThan(0);
+    const after = snapshot(root);
+    expect([...after.keys()].sort()).toEqual([...before.keys()].sort());
+    for (const [k, v] of before) expect(after.get(k)?.equals(v)).toBe(true);
+  });
+
+  test('apply performs all five transforms', () => {
+    const root = notionExport();
+    applyPlan(buildPlan(root));
+
+    const home = read(root, `/Home ${HOME}.md`);
+    expect(home).toContain(`[Content Plan](<Content Plan ${ID}.md>)`); // link decoded + angle-wrapped
+    expect(home).toContain('> [!note]'); // callout
+    expect(home).toContain('> Welcome!');
+    expect(home).toMatch(/!\[]\(home-[a-z0-9-]+-inline-1\.png\)/); // image embed
+    expect(home).not.toContain('data:image');
+
+    const assets = walkFiles(root).filter((f) => f.endsWith('.png'));
+    expect(assets).toHaveLength(1);
+
+    const stub = read(root, `/Content Plan ${ID}.md`);
+    expect(stub).toContain('| Headline | Status | Note |');
+    expect(stub).toContain('line1<br>line2'); // embedded newline flattened
+    expect(stub).toContain('a \\| b'); // pipe escaped
+    expect(stub).toContain(`[Alpha (v1)](<Content Plan/Alpha v1 ${R1}.md>)`); // title link, punct-matched
+    expect(walkFiles(root).some((f) => f.endsWith(`Alpha v1 ${R1}.md`))).toBe(true); // row page kept
+
+    const alpha = read(root, `/Content Plan/Alpha v1 ${R1}.md`);
+    expect(alpha.startsWith('---\n')).toBe(true);
+    expect(alpha).toContain('Status: Done');
+    expect(alpha).toContain('## Body'); // body preserved
+  });
+
+  test('is idempotent — a second apply changes nothing', () => {
+    const root = notionExport();
+    applyPlan(buildPlan(root));
+    const afterFirst = snapshot(root);
+
+    const secondPlan = buildPlan(root);
+    expect(secondPlan.changes).toHaveLength(0);
+    expect(secondPlan.assets).toHaveLength(0);
+    applyPlan(secondPlan);
+
+    const afterSecond = snapshot(root);
+    expect([...afterSecond.keys()].sort()).toEqual([...afterFirst.keys()].sort());
+    for (const [k, v] of afterFirst) expect(afterSecond.get(k)?.equals(v)).toBe(true);
+  });
+
+  test('refuses a non-Notion directory (no changes, flagged)', () => {
+    const root = makeTree({ 'notes.md': '# Notes\n\nPlain.\n', 'more.md': '# More\n' });
+    const { report, changes } = buildPlan(root);
+    expect(report.isNotionExport).toBe(false);
+    expect(changes).toHaveLength(0);
+  });
+
+  test('--force processes even when detection is negative', () => {
+    const root = makeTree({ 'page.md': '# P\n\n[x](Foo%20Bar.md)\n' });
+    const { changes } = buildPlan(root, { force: true });
+    expect(changes.some((c) => c.content.includes('[x](<Foo Bar.md>)'))).toBe(true);
+  });
+
+  test('--only limits the transforms run', () => {
+    const root = notionExport();
+    const { report } = buildPlan(root, { selected: new Set(['links']) });
+    expect(report.transforms.links).toBeGreaterThan(0);
+    expect(report.transforms.callouts).toBe(0);
+    expect(report.transforms.tables).toBe(0);
+  });
+
+  test('creates a table page for a database CSV that has no stub (orphan)', () => {
+    const root = makeTree({
+      [`Home ${HOME}.md`]: '# Home\n',
+      [`Customers ${ID}_all.csv`]: 'Name,Type\nAcme,Paid\n',
+      [`Customers/Acme ${R1}.md`]: '# Acme\n\nType: Paid\n',
+    });
+    const { changes, report } = buildPlan(root);
+    expect(report.stubsCreated).toBe(1);
+    const stub = changes.find((c) => c.path.endsWith(`Customers ${ID}.md`));
+    expect(stub).toBeDefined();
+    expect(stub?.content.startsWith('# Customers')).toBe(true);
+    expect(stub?.content).toContain('| Name | Type |');
+    expect(stub?.content).toContain(`[Acme](<Customers/Acme ${R1}.md>)`);
+  });
+
+  test('--remove-csv schedules the CSV for deletion', () => {
+    const root = notionExport();
+    const { deletions, report } = buildPlan(root, { removeCsv: true });
+    expect(deletions.some((p) => p.endsWith('_all.csv'))).toBe(true);
+    expect(report.csvsRemoved).toBeGreaterThan(0);
+  });
+
+  test('--remove-csv deletes the CSV, keeps the table + row pages, stays idempotent', () => {
+    const root = notionExport();
+    applyPlan(buildPlan(root, { removeCsv: true }));
+    expect(walkFiles(root).some((f) => f.endsWith('_all.csv'))).toBe(false); // CSV gone
+    expect(read(root, `/Content Plan ${ID}.md`)).toContain('| Headline | Status | Note |'); // table kept
+    expect(walkFiles(root).some((f) => f.endsWith(`Alpha v1 ${R1}.md`))).toBe(true); // row pages kept
+
+    const second = buildPlan(root, { removeCsv: true });
+    expect(second.changes).toHaveLength(0);
+    expect(second.deletions).toHaveLength(0);
+  });
+
+  test('redirects a cross-page link to a database CSV onto the table page (no dangle after --remove-csv)', () => {
+    const root = makeTree({
+      [`Hub ${HOME}.md`]: `# Hub\n\nSee [Customers](Customers%20${ID}_all.csv).\n`,
+      [`Customers ${ID}_all.csv`]: 'Name,Type\nAcme,Paid\n',
+      [`Customers/Acme ${R1}.md`]: '# Acme\n\nType: Paid\n',
+    });
+    applyPlan(buildPlan(root, { removeCsv: true }));
+    const hub = read(root, `/Hub ${HOME}.md`);
+    expect(hub).toContain(`[Customers](<Customers ${ID}.md>)`);
+    expect(hub).not.toContain('_all.csv');
+    expect(walkFiles(root).some((f) => f.endsWith(`Customers ${ID}.md`))).toBe(true);
+  });
+
+  test('reports wide tables and ambiguous title links', () => {
+    const wideHeader = Array.from({ length: 20 }, (_, i) => `col${i}`).join(',');
+    const root = makeTree({
+      [`Home ${HOME}.md`]: '# Home\n',
+      [`Big ${ID}_all.csv`]: `${wideHeader}\n`,
+      [`Dupes ${R1}_all.csv`]: 'Title,X\nNotes,1\nNotes,2\n',
+      [`Dupes/Notes ${R1}.md`]: '# Notes\n',
+      [`Dupes/Notes ${R2}.md`]: '# Notes\n',
+    });
+    const { report } = buildPlan(root);
+    expect(report.wideTables.length).toBeGreaterThan(0);
+    expect(report.ambiguousTitleLinks).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/plan.ts b/packages/cli/src/commands/migrate/notion/plan.ts
new file mode 100644
index 000000000..142984acc
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/plan.ts
@@ -0,0 +1,203 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { asideToCallout } from './aside-callout.ts';
+import { extractBase64Images } from './base64-images.ts';
+import { type DatabaseInfo, detectDatabases } from './databases.ts';
+import { decodeLinks } from './decode-links.ts';
+import { isNotionExport } from './detect.ts';
+import { walkFiles } from './fs-walk.ts';
+import { resolveKey } from './normalized-index.ts';
+import { propertiesToFrontmatter } from './properties-frontmatter.ts';
+import { buildStubPage, extractStubTitle, renderCsvTable } from './tables.ts';
+
+export type TransformId = 'links' | 'frontmatter' | 'callouts' | 'images' | 'tables';
+
+export const ALL_TRANSFORMS: readonly TransformId[] = [
+  'links',
+  'frontmatter',
+  'callouts',
+  'images',
+  'tables',
+];
+
+export interface Report {
+  isNotionExport: boolean;
+  transforms: Record<TransformId, number>;
+  assetsExtracted: number;
+  stubsCreated: number;
+  csvsRemoved: number;
+  wideTables: string[];
+  ambiguousTitleLinks: number;
+  unreadable: string[];
+  filesChanged: number;
+}
+
+export interface Plan {
+  changes: Array<{ path: string; content: string }>;
+  assets: Array<{ path: string; bytes: Uint8Array }>;
+  deletions: string[];
+  report: Report;
+}
+
+export interface PlanOptions {
+  selected?: ReadonlySet<TransformId>;
+  stripBase64?: boolean;
+  removeCsv?: boolean;
+  force?: boolean;
+}
+
+const MD = /\.mdx?$/i;
+
+function emptyReport(isNotionExport: boolean): Report {
+  return {
+    isNotionExport,
+    transforms: { links: 0, frontmatter: 0, callouts: 0, images: 0, tables: 0 },
+    assetsExtracted: 0,
+    stubsCreated: 0,
+    csvsRemoved: 0,
+    wideTables: [],
+    ambiguousTitleLinks: 0,
+    unreadable: [],
+    filesChanged: 0,
+  };
+}
+
+export function buildPlan(dir: string, opts: PlanOptions = {}): Plan {
+  const selected = opts.selected ?? new Set(ALL_TRANSFORMS);
+  const notion = isNotionExport(dir);
+  if (!notion && !opts.force) {
+    return { changes: [], assets: [], deletions: [], report: emptyReport(false) };
+  }
+
+  const report = emptyReport(notion);
+  const files = walkFiles(dir);
+  const databases = detectDatabases(files, {
+    onUnreadable: (path) => report.unreadable.push(path),
+  });
+  const doTables = selected.has('tables');
+
+  const dbByRowFile = new Map<string, DatabaseInfo>();
+  const existingStubs = new Set<string>();
+  for (const db of databases) {
+    if (db.stubPath) existingStubs.add(db.stubPath);
+    for (const rf of db.rowFiles) dbByRowFile.set(rf, db);
+  }
+
+  const changes: Plan['changes'] = [];
+  const assets: Plan['assets'] = [];
+  const deletions: string[] = [];
+
+  for (const file of files) {
+    if (!MD.test(file)) continue;
+    if (doTables && existingStubs.has(file)) continue;
+
+    let original: string;
+    try {
+      original = readFileSync(file, 'utf8');
+    } catch {
+      report.unreadable.push(file);
+      continue;
+    }
+    let content = original;
+    const bump = (id: TransformId, before: string) => {
+      if (content !== before) report.transforms[id] += 1;
+    };
+
+    if (selected.has('images')) {
+      const before = content;
+      const res = extractBase64Images(content, basename(file), { strip: opts.stripBase64 });
+      content = res.markdown;
+      for (const a of res.assets)
+        assets.push({ path: join(dirname(file), a.filename), bytes: a.bytes });
+      report.assetsExtracted += res.assets.length;
+      bump('images', before);
+    }
+
+    if (selected.has('callouts')) {
+      const before = content;
+      content = asideToCallout(content);
+      bump('callouts', before);
+    }
+
+    if (selected.has('frontmatter')) {
+      const db = dbByRowFile.get(file);
+      if (db) {
+        const before = content;
+        content = propertiesToFrontmatter(content, db.propertyKeys);
+        bump('frontmatter', before);
+      }
+    }
+
+    if (selected.has('links')) {
+      const before = content;
+      content = decodeLinks(content, { redirectCsv: doTables });
+      bump('links', before);
+    }
+
+    if (content !== original) changes.push({ path: file, content });
+  }
+
+  if (doTables) {
+    for (const db of databases) {
+      const rendered = renderCsvTable(db.csvText, {
+        linkForTitle: (title) => {
+          const res = resolveKey(db.folderIndex, title);
+          if (res.ambiguous) report.ambiguousTitleLinks += 1;
+          return res.path ? relative(dirname(db.stubTargetPath), res.path) : null;
+        },
+      });
+      if (rendered.columns === 0) continue; // empty/unreadable CSV — leave it alone
+
+      const writePath = db.stubPath ?? db.stubTargetPath;
+      let existing: string | null = null;
+      if (db.stubPath) {
+        try {
+          existing = readFileSync(db.stubPath, 'utf8');
+        } catch {
+          report.unreadable.push(db.stubPath);
+          continue;
+        }
+      }
+      const title =
+        existing !== null ? extractStubTitle(existing, db.fallbackTitle) : db.fallbackTitle;
+      let content = buildStubPage(title, rendered.table);
+      if (selected.has('links')) content = decodeLinks(content, { redirectCsv: doTables });
+      if (rendered.wide) report.wideTables.push(writePath);
+
+      if (existing === null) {
+        changes.push({ path: writePath, content });
+        report.stubsCreated += 1;
+        report.transforms.tables += 1;
+      } else if (content !== existing) {
+        changes.push({ path: writePath, content });
+        report.transforms.tables += 1;
+      }
+
+      if (opts.removeCsv) {
+        deletions.push(db.csvPath);
+        report.csvsRemoved += 1;
+      }
+    }
+  }
+
+  report.filesChanged = new Set(changes.map((c) => c.path)).size;
+  return { changes, assets, deletions, report };
+}
+
+export function applyPlan(plan: Plan): void {
+  for (const asset of plan.assets) {
+    mkdirSync(dirname(asset.path), { recursive: true });
+    writeFileSync(asset.path, asset.bytes);
+  }
+  for (const change of plan.changes) {
+    mkdirSync(dirname(change.path), { recursive: true });
+    writeFileSync(change.path, change.content, 'utf8');
+  }
+  for (const path of plan.deletions) {
+    try {
+      unlinkSync(path);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+  }
+}
diff --git a/packages/cli/src/commands/migrate/notion/properties-frontmatter.test.ts b/packages/cli/src/commands/migrate/notion/properties-frontmatter.test.ts
new file mode 100644
index 000000000..49842ecf0
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/properties-frontmatter.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'bun:test';
+import { propertiesToFrontmatter } from './properties-frontmatter.ts';
+
+const KEYS = new Set(['Status', 'Owner', 'Priority', 'White-Paper / E-Book?', 'Target Metric']);
+
+describe('propertiesToFrontmatter', () => {
+  test('lifts the property block under the H1 into leading frontmatter', () => {
+    const input = [
+      '# What are the perils of building today',
+      '',
+      'Status: Todo',
+      'Owner: Omar Nasser',
+      'Priority: Medium',
+      '',
+      '## Task description',
+      '',
+      'Provide an overview.',
+      '',
+    ].join('\n');
+    const out = propertiesToFrontmatter(input, KEYS);
+    expect(out).toBe(
+      [
+        '---',
+        'Status: Todo',
+        'Owner: Omar Nasser',
+        'Priority: Medium',
+        '---',
+        '',
+        '# What are the perils of building today',
+        '',
+        '## Task description',
+        '',
+        'Provide an overview.',
+        '',
+      ].join('\n'),
+    );
+  });
+
+  test('quotes keys and values that are not YAML-plain', () => {
+    const input = [
+      '# Row',
+      '',
+      'White-Paper / E-Book?: No',
+      'Target Metric: Blog to Demo > 0.38%',
+      '',
+    ].join('\n');
+    const out = propertiesToFrontmatter(input, KEYS);
+    expect(out).toContain('"White-Paper / E-Book?": No');
+    expect(out).toContain('Target Metric: "Blog to Demo > 0.38%"');
+  });
+
+  test('keeps comma-joined multi-select values as one quoted scalar (lossless)', () => {
+    const input = ['# Row', '', 'Status: Done, Shipped, Archived', ''].join('\n');
+    const out = propertiesToFrontmatter(input, new Set(['Status']));
+    expect(out).toContain('Status: "Done, Shipped, Archived"');
+  });
+
+  test('force-quotes YAML-typed values so text is not coerced to bool/null/number', () => {
+    const keys = new Set(['Active', 'Deleted', 'Count', 'Ratio', 'Hex']);
+    const input = [
+      '# Row',
+      '',
+      'Active: true',
+      'Deleted: null',
+      'Count: 1234',
+      'Ratio: 3.14',
+      'Hex: 0xFF',
+      '',
+    ].join('\n');
+    const out = propertiesToFrontmatter(input, keys);
+    expect(out).toContain('Active: "true"');
+    expect(out).toContain('Deleted: "null"');
+    expect(out).toContain('Count: "1234"');
+    expect(out).toContain('Ratio: "3.14"');
+    expect(out).toContain('Hex: "0xFF"');
+  });
+
+  test('does not capture body prose that merely looks like a key line', () => {
+    const input = [
+      '# Row',
+      '',
+      'Status: Todo',
+      '',
+      'Note: this is body prose, not a property.',
+      '',
+    ].join('\n');
+    const out = propertiesToFrontmatter(input, new Set(['Status']));
+    expect(out).toContain('Status: Todo');
+    expect(out).toContain('Note: this is body prose, not a property.');
+    expect(out.indexOf('Note:')).toBeGreaterThan(out.indexOf('---', 3));
+  });
+
+  test('leaves a page that already has frontmatter unchanged (idempotent)', () => {
+    const input = ['---', 'Status: Todo', '---', '', '# Row', ''].join('\n');
+    expect(propertiesToFrontmatter(input, KEYS)).toBe(input);
+  });
+
+  test('leaves a non-database page (no known keys matched) unchanged', () => {
+    const input = ['# Just a page', '', 'Some prose here.', ''].join('\n');
+    expect(propertiesToFrontmatter(input, KEYS)).toBe(input);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/properties-frontmatter.ts b/packages/cli/src/commands/migrate/notion/properties-frontmatter.ts
new file mode 100644
index 000000000..afdc14882
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/properties-frontmatter.ts
@@ -0,0 +1,68 @@
+const PLAIN = /^[A-Za-z0-9][A-Za-z0-9 ._/-]*$/;
+const YAML_TYPED = /^(true|false|null|~)$/i;
+const YAML_NUMERIC =
+  /^[-+]?(\.\d+|\d+(\.\d*)?([eE][-+]?\d+)?|0x[0-9a-fA-F]+|0o[0-7]+|\.inf|\.nan)$/i;
+
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function yamlScalar(value: string): string {
+  if (value === '') return '""';
+  if (YAML_TYPED.test(value) || YAML_NUMERIC.test(value)) return quote(value);
+  if (PLAIN.test(value)) return value;
+  return quote(value);
+}
+
+function propertyLine(key: string, value: string): string {
+  const k = PLAIN.test(key) ? key : quote(key);
+  return value.trimEnd() === '' ? `${k}:` : `${k}: ${yamlScalar(value.trimEnd())}`;
+}
+
+export function propertiesToFrontmatter(
+  markdown: string,
+  propertyKeys: ReadonlySet<string>,
+): string {
+  if (propertyKeys.size === 0) return markdown;
+  if (/^---\r?\n/.test(markdown)) return markdown; // already has frontmatter
+
+  const lines = markdown.split('\n');
+
+  let h1 = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^#\s+/.test(lines[i] as string)) {
+      h1 = i;
+      break;
+    }
+    if ((lines[i] as string).trim() !== '') return markdown;
+  }
+  if (h1 === -1) return markdown;
+
+  let i = h1 + 1;
+  while (i < lines.length && (lines[i] as string).trim() === '') i++;
+  const props: Array<[string, string]> = [];
+  while (i < lines.length) {
+    const match = (lines[i] as string).match(/^([^:]+):\s?(.*)$/);
+    if (!match) break;
+    const key = (match[1] as string).trim();
+    if (!propertyKeys.has(key)) break;
+    props.push([key, match[2] as string]);
+    i++;
+  }
+  if (props.length === 0) return markdown;
+
+  const bodyAfter = lines.slice(i);
+  while (bodyAfter.length > 0 && (bodyAfter[0] as string).trim() === '') bodyAfter.shift();
+
+  const parts: string[] = [
+    '---',
+    ...props.map(([k, v]) => propertyLine(k, v)),
+    '---',
+    '',
+    lines[h1] as string,
+  ];
+  if (bodyAfter.length > 0) parts.push('', ...bodyAfter);
+
+  const result = parts.join('\n').replace(/\n+$/, '');
+  return markdown.endsWith('\n') ? `${result}\n` : result;
+}
diff --git a/packages/cli/src/commands/migrate/notion/report.ts b/packages/cli/src/commands/migrate/notion/report.ts
new file mode 100644
index 000000000..dd4b9c11d
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/report.ts
@@ -0,0 +1,47 @@
+import type { Report, TransformId } from './plan.ts';
+
+const LABELS: Record<TransformId, string> = {
+  images: 'Inline base64 images extracted',
+  callouts: 'Notion <aside> callouts converted',
+  frontmatter: 'Row properties lifted to frontmatter',
+  tables: 'Databases rendered as tables',
+  links: 'Internal links decoded',
+};
+
+const ORDER: readonly TransformId[] = ['images', 'callouts', 'frontmatter', 'tables', 'links'];
+
+export function formatReport(report: Report, o: { applied: boolean; dir: string }): string {
+  const lines: string[] = [];
+  lines.push(
+    o.applied ? `Applied Notion cleanup in ${o.dir}` : `Dry run — no changes written (${o.dir})`,
+  );
+  for (const id of ORDER) {
+    lines.push(`  ${LABELS[id]}: ${report.transforms[id]}`);
+  }
+  lines.push(`  Assets written: ${report.assetsExtracted}`);
+  if (report.stubsCreated > 0) {
+    lines.push(`  Database pages created (CSVs without a stub): ${report.stubsCreated}`);
+  }
+  if (report.csvsRemoved > 0) {
+    lines.push(`  CSV files removed: ${report.csvsRemoved}`);
+  }
+  lines.push(`  Files changed: ${report.filesChanged}`);
+  if (report.ambiguousTitleLinks > 0) {
+    lines.push(`  Ambiguous title links left as plain text: ${report.ambiguousTitleLinks}`);
+  }
+  if (report.wideTables.length > 0) {
+    lines.push(`  Wide tables (>15 columns): ${report.wideTables.length}`);
+  }
+  if (report.unreadable.length > 0) {
+    lines.push(`  Skipped unreadable files: ${report.unreadable.length}`);
+  }
+  if (!o.applied && report.filesChanged + report.assetsExtracted + report.csvsRemoved > 0) {
+    lines.push('');
+    lines.push('Re-run with --apply to write these changes.');
+  }
+  return lines.join('\n');
+}
+
+export function formatReportJson(report: Report, o: { applied: boolean }): string {
+  return JSON.stringify({ applied: o.applied, ...report }, null, 2);
+}
diff --git a/packages/cli/src/commands/migrate/notion/tables.test.ts b/packages/cli/src/commands/migrate/notion/tables.test.ts
new file mode 100644
index 000000000..c084a6f30
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/tables.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test';
+import { buildStubPage, extractStubTitle, renderCsvTable } from './tables.ts';
+
+describe('renderCsvTable', () => {
+  test('renders a header, separator, and rows', () => {
+    const { table, columns, wide } = renderCsvTable('Name,Status\nAlpha,Done\nBeta,Todo\n');
+    expect(columns).toBe(2);
+    expect(wide).toBe(false);
+    expect(table).toBe(
+      ['| Name | Status |', '| --- | --- |', '| Alpha | Done |', '| Beta | Todo |'].join('\n'),
+    );
+  });
+
+  test('flattens embedded newlines to <br> and escapes pipes', () => {
+    const { table } = renderCsvTable('Name,Note\n"Alpha","line one\nline two"\n"Beta","a | b"\n');
+    expect(table).toContain('| Alpha | line one<br>line two |');
+    expect(table).toContain('| Beta | a \\| b |');
+  });
+
+  test('flags a wide table past the threshold but still renders it', () => {
+    const header = Array.from({ length: 40 }, (_, i) => `c${i}`).join(',');
+    const { columns, wide, table } = renderCsvTable(`${header}\n`);
+    expect(columns).toBe(40);
+    expect(wide).toBe(true);
+    expect(table.startsWith('| c0 |')).toBe(true);
+  });
+
+  test('links the title column when the resolver returns a path', () => {
+    const { table } = renderCsvTable('Title,Status\nMy Row,Done\n', {
+      linkForTitle: (t) => (t === 'My Row' ? 'DB/My Row abc.md' : null),
+    });
+    expect(table).toContain('| [My Row](<DB/My Row abc.md>) | Done |');
+  });
+
+  test('falls back to plain text when the resolver returns null', () => {
+    const { table } = renderCsvTable('Title,Status\nGhost,Done\n', { linkForTitle: () => null });
+    expect(table).toContain('| Ghost | Done |');
+  });
+
+  test('honors a non-zero title column', () => {
+    const { table } = renderCsvTable('Status,Title\nDone,My Row\n', {
+      titleColumn: 1,
+      linkForTitle: () => 'row.md',
+    });
+    expect(table).toContain('| Done | [My Row](row.md) |');
+  });
+
+  test('renders a header-only CSV as a table with no body rows', () => {
+    const { table } = renderCsvTable('A,B,C\n');
+    expect(table).toBe(['| A | B | C |', '| --- | --- | --- |'].join('\n'));
+  });
+});
+
+describe('buildStubPage + extractStubTitle', () => {
+  test('regeneration is idempotent for a fixed (title, csv)', () => {
+    const csv = 'Name,Status\nAlpha,Done\n';
+    const title = extractStubTitle(
+      '# Content Plan\n\n[Content Plan](Content%20Plan_all.csv)\n',
+      'fallback',
+    );
+    expect(title).toBe('Content Plan');
+    const once = buildStubPage(title, renderCsvTable(csv).table);
+    const twice = buildStubPage(extractStubTitle(once, 'fallback'), renderCsvTable(csv).table);
+    expect(twice).toBe(once);
+  });
+});
diff --git a/packages/cli/src/commands/migrate/notion/tables.ts b/packages/cli/src/commands/migrate/notion/tables.ts
new file mode 100644
index 000000000..45473e48e
--- /dev/null
+++ b/packages/cli/src/commands/migrate/notion/tables.ts
@@ -0,0 +1,60 @@
+import { parseCsv } from './csv.ts';
+
+export interface RenderTableOptions {
+  wideThreshold?: number;
+  titleColumn?: number;
+  linkForTitle?: (title: string) => string | null;
+}
+
+export interface RenderedTable {
+  table: string;
+  columns: number;
+  wide: boolean;
+}
+
+function escapeCell(value: string): string {
+  return value.replace(/\r\n|\r|\n/g, '<br>').replace(/\|/g, '\\|');
+}
+
+function linkTarget(path: string): string {
+  return /\s/.test(path) ? `<${path}>` : path;
+}
+
+export function renderCsvTable(csvText: string, opts: RenderTableOptions = {}): RenderedTable {
+  const { header, rows } = parseCsv(csvText);
+  const columns = header.length;
+  if (columns === 0) return { table: '', columns: 0, wide: false };
+
+  const wideThreshold = opts.wideThreshold ?? 15;
+  const titleCol = opts.titleColumn ?? 0;
+
+  const headerLine = `| ${header.map(escapeCell).join(' | ')} |`;
+  const sepLine = `| ${header.map(() => '---').join(' | ')} |`;
+  const bodyLines = rows.map((row) => {
+    const cells = header.map((_h, ci) => {
+      const raw = row[ci] ?? '';
+      const display = escapeCell(raw);
+      if (ci === titleCol && opts.linkForTitle && raw.trim() !== '') {
+        const link = opts.linkForTitle(raw);
+        if (link) return `[${display}](${linkTarget(link)})`;
+      }
+      return display;
+    });
+    return `| ${cells.join(' | ')} |`;
+  });
+
+  return {
+    table: [headerLine, sepLine, ...bodyLines].join('\n'),
+    columns,
+    wide: columns > wideThreshold,
+  };
+}
+
+export function extractStubTitle(stubMarkdown: string, fallback: string): string {
+  const match = stubMarkdown.match(/^#\s+(.+)$/m);
+  return match ? (match[1] as string).trim() : fallback;
+}
+
+export function buildStubPage(title: string, table: string): string {
+  return `# ${title}\n\n${table}\n`;
+}