@moxn/kb-migrate 0.4.24 → 0.4.26

package/dist/client.d.ts

@@ -53,7 +53,7 @@ export declare class MoxnClient {
      */
     addDatabaseColumn(databaseId: string, input: {
         name: string;
-        type: 'select' | 'multi_select' | 'status' | 'checkbox' | 'number' | 'date' | 'text' | 'url' | 'email';
+        type: 'select' | 'multi_select' | 'status' | 'checkbox' | 'number' | 'date' | 'text' | 'url' | 'email' | 'page_ref';
         optionTagIds?: string[];
         newOptionParentPath?: string;
         config?: Record<string, unknown>;
@@ -176,5 +176,26 @@ export declare class MoxnClient {
      * Set a scalar property value on a document in a database.
      */
     setPropertyValue(databaseId: string, documentId: string, columnName: string, value: string | number | boolean | null): Promise<void>;
+    /**
+     * Create or upsert a Notion page → KB document mapping.
+     */
+    createNotionPageMapping(input: {
+        kbDocumentId: string;
+        notionPageId: string;
+        importSource: 'import' | 'export';
+        notionPageTitle?: string;
+    }): Promise<void>;
+    /**
+     * Get all Notion database → KB database mappings for the tenant.
+     * Returns a Map of notionDatabaseId → kbDatabaseId.
+     */
+    getAllDatabaseMappings(): Promise<Map<string, string>>;
+    /**
+     * Get a KB database by ID. Returns null if not found (404).
+     */
+    getDatabase(databaseId: string): Promise<{
+        id: string;
+        name: string;
+    } | null>;
     private isConflictError;
 }

package/dist/client.js

@@ -522,6 +522,52 @@ export class MoxnClient {
             throw new Error(body.error || `Failed to set property value: ${response.status}`);
         }
     }
+    // ──────────────────────────────────────────────
+    // Notion page mapping methods
+    // ──────────────────────────────────────────────
+    /**
+     * Create or upsert a Notion page → KB document mapping.
+     */
+    async createNotionPageMapping(input) {
+        const response = await fetch(`${this.apiUrl}/api/v1/kb/notion-mappings`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify(input),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(body.error || `Failed to create page mapping: ${response.status}`);
+        }
+    }
+    /**
+     * Get all Notion database → KB database mappings for the tenant.
+     * Returns a Map of notionDatabaseId → kbDatabaseId.
+     */
+    async getAllDatabaseMappings() {
+        const response = await fetch(`${this.apiUrl}/api/v1/kb/notion-mappings/databases`, {
+            headers: { 'x-api-key': this.apiKey },
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(body.error || `Failed to get database mappings: ${response.status}`);
+        }
+        const data = await response.json();
+        const map = new Map();
+        for (const mapping of data.mappings) {
+            map.set(mapping.notionDatabaseId, mapping.kbDatabaseId);
+        }
+        return map;
+    }
+    /**
+     * Get a KB database by ID. Returns null if not found (404).
+     */
+    async getDatabase(databaseId) {
+        const databases = await this.listDatabases();
+        return databases.find((db) => db.id === databaseId) ?? null;
+    }
     isConflictError(error) {
         return (error instanceof Error &&
             'documentId' in error &&

package/dist/index.js

@@ -16,6 +16,8 @@ import { Command } from 'commander';
 import { LocalSource } from './sources/local.js';
 import { NotionSource } from './sources/notion.js';
 import { notionColorToHex } from './sources/notion-api.js';
+import { getPageTitle } from './sources/notion-blocks.js';
+import { slugify } from './sources/notion.js';
 import { MoxnClient } from './client.js';
 import { runExport } from './export.js';
 import { runNotionExport } from './export-notion.js';
@@ -42,6 +44,21 @@ async function runMigration(source, options) {
         console.log(`Processing: ${doc.sourcePath}${progress}`);
         const result = await client.migrateDocument(doc, options.basePath, options.onConflict, options.dryRun);
         results.push(result);
+        // Store Notion page → KB document mapping (fire-and-forget)
+        if (result.sourcePageId &&
+            result.documentId &&
+            (result.status === 'created' || result.status === 'updated')) {
+            client
+                .createNotionPageMapping({
+                kbDocumentId: result.documentId,
+                notionPageId: result.sourcePageId,
+                importSource: 'import',
+                notionPageTitle: doc.metadata?.notionTitle,
+            })
+                .catch((err) => {
+                console.warn(`  Warning: page mapping failed for ${result.sourcePageId}: ${err instanceof Error ? err.message : err}`);
+            });
+        }
         // Track consecutive failures for circuit breaker
         if (result.status === 'failed') {
             consecutiveFailures++;
@@ -63,12 +80,15 @@ async function runMigration(source, options) {
         // Circuit breaker: abort after too many consecutive failures
         if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
             console.error(`\nAborting: ${MAX_CONSECUTIVE_FAILURES} consecutive failures. ` +
-                'Last error: ' + (result.error || 'unknown') + '\n' +
+                'Last error: ' +
+                (result.error || 'unknown') +
+                '\n' +
                 'Fix the underlying issue and retry. Remaining documents will be skipped.');
             break;
         }
     }
-    // Build summary
+    // Build summary (include extraction stats if available)
+    const extractionStats = source.getExtractionStats?.();
     const summary = {
         total: results.length,
         created: results.filter((r) => r.status === 'created').length,
@@ -76,6 +96,12 @@ async function runMigration(source, options) {
         skipped: results.filter((r) => r.status === 'skipped').length,
         failed: results.filter((r) => r.status === 'failed').length,
         duration: Date.now() - startTime,
+        ...(extractionStats && {
+            discovered: extractionStats.discovered,
+            skippedDuringExtraction: extractionStats.skippedEmpty.length +
+                extractionStats.skippedNoContent.length +
+                extractionStats.errors.length,
+        }),
     };
     const log = {
         timestamp: new Date().toISOString(),
@@ -101,6 +127,15 @@ function printSummary(log) {
     console.log(`Base path: ${log.basePath}`);
     console.log(`Duration: ${(log.summary.duration / 1000).toFixed(1)}s`);
     console.log('');
+    // Show reconciliation if extraction stats are available
+    if (log.summary.discovered != null && log.summary.skippedDuringExtraction != null) {
+        console.log(`Discovered:  ${log.summary.discovered} pages`);
+        if (log.summary.skippedDuringExtraction > 0) {
+            console.log(`Skipped:     ${log.summary.skippedDuringExtraction} (empty or errored during extraction)`);
+        }
+        console.log(`Processed:   ${log.summary.total}`);
+        console.log('');
+    }
     console.log(`Total:   ${log.summary.total}`);
     console.log(`Created: ${log.summary.created}`);
     console.log(`Updated: ${log.summary.updated}`);
@@ -432,9 +467,20 @@ program
         if (!opts.dryRun && dbImports.length > 0) {
             console.log(`\nPre-creating ${dbImports.length} database(s)...`);
             const preClient = new MoxnClient(migrationOptions);
+            // Fetch existing database mappings (1 API call) to avoid duplicates
+            let existingMappings = new Map();
+            try {
+                existingMappings = await preClient.getAllDatabaseMappings();
+                if (existingMappings.size > 0) {
+                    console.log(`  Found ${existingMappings.size} existing database mapping(s).`);
+                }
+            }
+            catch (error) {
+                console.warn(`  Warning: Could not fetch existing mappings: ${error instanceof Error ? error.message : error}`);
+            }
             for (const dbImport of dbImports) {
                 try {
-                    const kbDbId = await preCreateNotionDatabase(preClient, dbImport);
+                    const kbDbId = await preCreateNotionDatabase(preClient, dbImport, existingMappings);
                     databaseIdMap.set(dbImport.notionDatabaseId, kbDbId);
                 }
                 catch (error) {
@@ -443,10 +489,77 @@ program
             }
             // Make the map available during extraction
             source.setDatabaseIdMap(databaseIdMap);
-            console.log(`  ${databaseIdMap.size} database(s) pre-created for embed resolution.\n`);
+            console.log(`  ${databaseIdMap.size} database(s) ready for embed resolution.\n`);
         }
         // Step 3: Run page migration (validate is idempotent, extract uses databaseIdMap)
         const log = await runMigration(source, migrationOptions);
+        // Step 3b: Resolve inline databases discovered during extraction
+        if (!opts.dryRun) {
+            const unresolvedDbs = source.getUnresolvedInlineDatabases();
+            if (unresolvedDbs.size > 0) {
+                console.log(`\nResolving ${unresolvedDbs.size} inline database(s) discovered during extraction...`);
+                const inlineClient = new MoxnClient(migrationOptions);
+                const notionApi = source.getNotionApiClient();
+                // Fetch current mappings to avoid duplicates (may have changed since pre-create)
+                let currentMappings = new Map();
+                try {
+                    currentMappings = await inlineClient.getAllDatabaseMappings();
+                }
+                catch {
+                    // Non-fatal — will create new databases
+                }
+                let inlineCreated = 0;
+                for (const [notionDbId, title] of unresolvedDbs) {
+                    // Skip if already mapped (could happen if previously imported)
+                    if (databaseIdMap.has(notionDbId) || currentMappings.has(notionDbId)) {
+                        continue;
+                    }
+                    try {
+                        // Fetch database schema from Notion
+                        const notionDb = await notionApi.getDatabase(notionDbId);
+                        const { parseDatabaseSchema } = await import('./sources/notion-databases.js');
+                        const schema = parseDatabaseSchema(notionDb);
+                        // Create KB database
+                        const kbDb = await inlineClient.createDatabase({
+                            name: schema.name || title,
+                            description: schema.description || undefined,
+                        });
+                        // Store mapping
+                        try {
+                            await inlineClient.createNotionDatabaseMapping({
+                                kbDatabaseId: kbDb.id,
+                                notionDatabaseId: notionDbId,
+                                notionDatabaseTitle: schema.name || title,
+                            });
+                        }
+                        catch {
+                            // Non-fatal — database created but mapping may fail
+                        }
+                        databaseIdMap.set(notionDbId, kbDb.id);
+                        // Query entries and add to dbImports for finalization
+                        const entries = await notionApi.queryDatabase(notionDbId);
+                        if (entries.length > 0) {
+                            dbImports.push({
+                                notionDatabaseId: notionDbId,
+                                schema,
+                                entries: entries.map((entry) => {
+                                    const entryTitle = getPageTitle(entry);
+                                    return { page: entry, kbPath: slugify(entryTitle) };
+                                }),
+                            });
+                        }
+                        inlineCreated++;
+                        console.log(`  Created inline database: ${schema.name || title} (${kbDb.id}) — ${entries.length} entries`);
+                    }
+                    catch (error) {
+                        console.warn(`  Warning: Failed to create inline database "${title}" (${notionDbId}): ${error instanceof Error ? error.message : error}`);
+                    }
+                }
+                if (inlineCreated > 0) {
+                    console.log(`  Created ${inlineCreated} inline database(s). Re-run with --on-conflict update to resolve embeds.`);
+                }
+            }
+        }
         // Step 4: Resolve cross-references (between page migration and database finalization)
         if (!opts.dryRun) {
             const refsWithData = log.results.filter((r) => r.references?.length && r.sectionIds?.length);
@@ -581,15 +694,26 @@ program
  * Called before document extraction so child_database blocks can resolve.
  * Returns the KB database ID.
  */
-async function preCreateNotionDatabase(client, dbImport) {
+async function preCreateNotionDatabase(client, dbImport, existingMappings) {
     const { schema } = dbImport;
+    // Check if we already have a mapping for this Notion database
+    const existingKbDbId = existingMappings.get(dbImport.notionDatabaseId);
+    if (existingKbDbId) {
+        // Verify the KB database still exists
+        const existingDb = await client.getDatabase(existingKbDbId);
+        if (existingDb) {
+            console.log(`  Reusing existing database: ${existingDb.name} (${existingKbDbId})`);
+            return existingKbDbId;
+        }
+        console.log(`  Mapped database ${existingKbDbId} no longer exists, creating new one.`);
+    }
     console.log(`  Pre-creating database: ${schema.name}`);
     const db = await client.createDatabase({
         name: schema.name,
         description: schema.description || undefined,
     });
     console.log(`    Database created: ${db.id}`);
-    // Store Notion → KB database mapping
+    // Store Notion → KB database mapping (upsert handles duplicates)
     try {
         await client.createNotionDatabaseMapping({
             kbDatabaseId: db.id,
@@ -688,6 +812,8 @@ async function importNotionDatabase(client, dbImport, log, options, preCreatedDb
     // 3. Link entries and assign tags
     // Build a map of KB path → { documentId, branchId } from migration results
     const docByPath = new Map();
+    // Build a map of Notion page ID → KB document ID for page_ref resolution
+    const notionIdToDocId = new Map();
     for (const result of log.results) {
         if (result.documentId && result.branchId) {
             docByPath.set(result.documentPath, {
@@ -695,6 +821,9 @@ async function importNotionDatabase(client, dbImport, log, options, preCreatedDb
                 branchId: result.branchId,
             });
         }
+        if (result.sourcePageId && result.documentId) {
+            notionIdToDocId.set(result.sourcePageId, result.documentId);
+        }
     }
     let linkedCount = 0;
     for (const entry of entries) {
@@ -749,6 +878,19 @@ async function importNotionDatabase(client, dbImport, log, options, preCreatedDb
                     case 'email':
                         value = scalarVal.textValue ?? null;
                         break;
+                    case 'page_ref': {
+                        // Resolve notion:XXX markers to KB document IDs
+                        const refs = JSON.parse(scalarVal.textValue ?? '[]');
+                        const resolvedRefs = refs.map((ref) => {
+                            if (ref.startsWith('notion:')) {
+                                const notionId = ref.substring(7);
+                                return notionIdToDocId.get(notionId) ?? ref;
+                            }
+                            return ref;
+                        });
+                        value = JSON.stringify(resolvedRefs);
+                        break;
+                    }
                 }
                 if (value != null) {
                     try {

package/dist/sources/base.d.ts

@@ -40,4 +40,15 @@ export declare abstract class MigrationSource<TConfig extends SourceConfig = Sou
      * Returns undefined if count cannot be determined without full extraction
      */
     abstract getDocumentCount(): Promise<number | undefined>;
+    /**
+     * Get extraction stats for reconciling discovered vs extracted counts.
+     * Only available after extract() completes.
+     */
+    getExtractionStats?(): {
+        discovered: number;
+        extracted: number;
+        skippedEmpty: string[];
+        skippedNoContent: string[];
+        errors: string[];
+    };
 }

package/dist/sources/notion-blocks.d.ts

@@ -16,6 +16,8 @@ export type UnsupportedBlockTracker = Map<string, number>;
  * H2 headings create section boundaries.
  * Content before the first H2 goes into an "Introduction" section.
  */
+/** Collects Notion database IDs that were encountered but not in databaseIdMap. */
+export type UnresolvedChildDatabaseCollector = Map<string, string>;
 export declare function blocksToSections(blocks: NotionBlock[], client: NotionApiClient, pagePathMap: PagePathMap, options?: {
     /** Track synced block IDs to detect cycles. */
     visitedSyncedBlocks?: Set<string>;
@@ -23,6 +25,8 @@ export declare function blocksToSections(blocks: NotionBlock[], client: NotionAp
     databaseIdMap?: Map<string, string>;
     /** Accumulates counts of unsupported block types (caller-owned). */
     unsupportedBlocks?: UnsupportedBlockTracker;
+    /** Collects inline databases not yet mapped (caller-owned). */
+    unresolvedChildDatabases?: UnresolvedChildDatabaseCollector;
 }): Promise<SectionInput[]>;
 /** Convert rich text array to markdown string. */
 export declare function richTextToMarkdown(richText: NotionRichText[]): string;

package/dist/sources/notion-blocks.js

@@ -4,19 +4,11 @@
  * Section boundaries are created at H2 headings.
  * Rich text is converted to markdown.
  */
-// ============================================
-// Main entry point
-// ============================================
-/**
- * Convert a page's blocks into Moxn sections.
- *
- * H2 headings create section boundaries.
- * Content before the first H2 goes into an "Introduction" section.
- */
 export async function blocksToSections(blocks, client, pagePathMap, options) {
     const visitedSyncedBlocks = options?.visitedSyncedBlocks ?? new Set();
     const databaseIdMap = options?.databaseIdMap;
     const unsupportedBlocks = options?.unsupportedBlocks;
+    const unresolvedChildDatabases = options?.unresolvedChildDatabases;
     const sections = [];
     let currentSectionName = 'Introduction';
     let currentBlocks = [];
@@ -36,7 +28,7 @@ export async function blocksToSections(blocks, client, pagePathMap, options) {
             continue;
         }
         // Convert block to content blocks
-        const converted = await convertBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks);
+        const converted = await convertBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
         currentBlocks.push(...converted);
     }
     // Flush last section
@@ -52,7 +44,7 @@ export async function blocksToSections(blocks, client, pagePathMap, options) {
 // ============================================
 // Block conversion
 // ============================================
-async function convertBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks) {
+async function convertBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const results = [];
     switch (block.type) {
         case 'paragraph':
@@ -82,10 +74,10 @@ async function convertBlock(block, client, pagePathMap, visitedSyncedBlocks, dat
             results.push(...convertToDo(block));
             break;
         case 'quote':
-            results.push(...(await convertQuote(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks)));
+            results.push(...(await convertQuote(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases)));
             break;
         case 'callout':
-            results.push(...(await convertCallout(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks)));
+            results.push(...(await convertCallout(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases)));
             break;
         case 'divider':
             results.push(textBlock('---'));
@@ -94,7 +86,7 @@ async function convertBlock(block, client, pagePathMap, visitedSyncedBlocks, dat
             results.push(...(await convertTable(block, client)));
             break;
         case 'toggle':
-            results.push(...(await convertToggle(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks)));
+            results.push(...(await convertToggle(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases)));
             break;
         case 'bookmark':
             results.push(...convertBookmark(block));
@@ -120,13 +112,13 @@ async function convertBlock(block, client, pagePathMap, visitedSyncedBlocks, dat
             // Just note it in the content.
             break;
         case 'child_database':
-            results.push(...convertChildDatabase(block, databaseIdMap));
+            results.push(...convertChildDatabase(block, databaseIdMap, unresolvedChildDatabases));
             break;
         case 'synced_block':
-            results.push(...(await convertSyncedBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks)));
+            results.push(...(await convertSyncedBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases)));
             break;
         case 'column_list':
-            results.push(...(await convertColumnList(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks)));
+            results.push(...(await convertColumnList(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases)));
             break;
         case 'column':
             // Columns are handled by column_list
@@ -169,7 +161,7 @@ async function convertBlock(block, client, pagePathMap, visitedSyncedBlocks, dat
             ? '  '
             : undefined;
         const children = await client.getBlockChildren(block.id);
-        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, indent, databaseIdMap, unsupportedBlocks);
+        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, indent, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
         results.push(...childBlocks);
     }
     return results;
@@ -215,7 +207,7 @@ function convertToDo(block) {
     const text = richTextToMarkdown(td.to_do.rich_text);
     return [textBlock(`${checkbox} ${text}`)];
 }
-async function convertQuote(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks) {
+async function convertQuote(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const q = block;
     const text = richTextToMarkdown(q.quote.rich_text);
     if (!text && !block.has_children)
@@ -229,12 +221,12 @@ async function convertQuote(block, client, pagePathMap, visitedSyncedBlocks, dat
     const results = quoted ? [textBlock(quoted)] : [];
     if (block.has_children) {
         const children = await client.getBlockChildren(block.id);
-        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, '> ', databaseIdMap, unsupportedBlocks);
+        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, '> ', databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
         results.push(...childBlocks);
     }
     return results;
 }
-async function convertCallout(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks) {
+async function convertCallout(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const c = block;
     const text = richTextToMarkdown(c.callout.rich_text);
     const emoji = c.callout.icon?.emoji ?? '';
@@ -246,7 +238,7 @@ async function convertCallout(block, client, pagePathMap, visitedSyncedBlocks, d
     const results = [textBlock(quoted)];
     if (block.has_children) {
         const children = await client.getBlockChildren(block.id);
-        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, '> ', databaseIdMap, unsupportedBlocks);
+        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, '> ', databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
         results.push(...childBlocks);
     }
     return results;
@@ -275,18 +267,18 @@ async function convertTable(block, client) {
     }
     return [textBlock(lines.join('\n'))];
 }
-async function convertToggle(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks) {
+async function convertToggle(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const t = block;
     const header = richTextToMarkdown(t.toggle.rich_text);
     const results = [textBlock(`**${header}**`)];
     if (block.has_children) {
         const children = await client.getBlockChildren(block.id);
-        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, '> ', databaseIdMap, unsupportedBlocks);
+        const childBlocks = await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, '> ', databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
         results.push(...childBlocks);
     }
     return results;
 }
-function convertChildDatabase(block, databaseIdMap) {
+function convertChildDatabase(block, databaseIdMap, unresolvedChildDatabases) {
     const cd = block;
     const title = cd.child_database?.title || 'Untitled Database';
     const notionDbId = normalizeId(block.id);
@@ -295,7 +287,10 @@ function convertChildDatabase(block, databaseIdMap) {
     if (kbDatabaseId) {
         return [{ blockType: 'database_embed', databaseId: kbDatabaseId }];
     }
-    // No mapping available — emit text placeholder
+    // No mapping available — collect for later creation and emit text placeholder
+    if (unresolvedChildDatabases) {
+        unresolvedChildDatabases.set(notionDbId, title);
+    }
     console.warn(`  No KB mapping for Notion database "${title}" (${notionDbId})`);
     return [textBlock(`*(Embedded database: ${title})*`)];
 }
@@ -406,7 +401,7 @@ function convertLinkToPage(block, pagePathMap) {
     // Target not in import set
     return [textBlock(`*(Link to Notion page: ${targetId})*`)];
 }
-async function convertSyncedBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks) {
+async function convertSyncedBlock(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const sb = block;
     // Get the source block ID (either this block or the original)
     const sourceId = sb.synced_block.synced_from?.block_id ?? block.id;
@@ -417,19 +412,19 @@ async function convertSyncedBlock(block, client, pagePathMap, visitedSyncedBlock
     visitedSyncedBlocks.add(sourceId);
     try {
         const children = await client.getBlockChildren(sourceId);
-        return await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, undefined, databaseIdMap, unsupportedBlocks);
+        return await convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, undefined, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
     }
     finally {
         visitedSyncedBlocks.delete(sourceId);
     }
 }
-async function convertColumnList(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks) {
+async function convertColumnList(block, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const children = await client.getBlockChildren(block.id);
     const results = [];
     for (const column of children) {
         if (column.type === 'column' && column.has_children) {
             const columnChildren = await client.getBlockChildren(column.id);
-            const converted = await convertAndMergeChildren(columnChildren, client, pagePathMap, visitedSyncedBlocks, undefined, databaseIdMap, unsupportedBlocks);
+            const converted = await convertAndMergeChildren(columnChildren, client, pagePathMap, visitedSyncedBlocks, undefined, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
             results.push(...converted);
         }
     }
@@ -578,10 +573,10 @@ function mergeConsecutiveListBlocks(blocks) {
 /**
  * Convert children blocks, merge consecutive list items, and optionally indent.
  */
-async function convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, indent, databaseIdMap, unsupportedBlocks) {
+async function convertAndMergeChildren(children, client, pagePathMap, visitedSyncedBlocks, indent, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases) {
     const blocks = [];
     for (const child of children) {
-        const converted = await convertBlock(child, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks);
+        const converted = await convertBlock(child, client, pagePathMap, visitedSyncedBlocks, databaseIdMap, unsupportedBlocks, unresolvedChildDatabases);
         blocks.push(...converted);
     }
     const merged = mergeConsecutiveListBlocks(blocks);

package/dist/sources/notion-databases.d.ts

@@ -30,8 +30,8 @@ export interface MappedColumn {
 export interface ScalarColumn {
     notionPropertyId: string;
     notionPropertyName: string;
-    notionType: 'number' | 'date' | 'url' | 'email' | 'rich_text' | 'checkbox';
-    moxnType: 'number' | 'date' | 'url' | 'email' | 'text';
+    notionType: 'number' | 'date' | 'url' | 'email' | 'rich_text' | 'checkbox' | 'relation';
+    moxnType: 'number' | 'date' | 'url' | 'email' | 'text' | 'page_ref';
 }
 /** Parsed Notion column that will be rendered as text in a Properties section. */
 export interface UnmappedColumn {
@@ -50,7 +50,7 @@ export interface ParsedDatabaseSchema {
 /** Scalar value for a single database entry property. */
 export interface ScalarValue {
     columnName: string;
-    moxnType: 'number' | 'date' | 'url' | 'email' | 'text';
+    moxnType: 'number' | 'date' | 'url' | 'email' | 'text' | 'page_ref';
     textValue?: string | null;
     numberValue?: number | null;
     dateValue?: string | null;

package/dist/sources/notion-databases.js

@@ -123,6 +123,14 @@ export function parseDatabaseSchema(db) {
                 moxnType: 'text',
             });
         }
+        else if (prop.type === 'relation') {
+            scalarColumns.push({
+                notionPropertyId: prop.id,
+                notionPropertyName: propName,
+                notionType: 'relation',
+                moxnType: 'page_ref',
+            });
+        }
         else {
             // Warn on property types that have no meaningful static value
             if (prop.type === 'button' || prop.type === 'ai_text') {
@@ -175,9 +183,24 @@ export function parseEntryValues(page, schema) {
         // Check if this is a scalar column
         const scalar = scalarByName.get(propName);
         if (scalar) {
-            const extracted = extractScalarValue(propValue, scalar);
-            if (extracted) {
-                scalarValues.set(propName, extracted);
+            // page_ref columns extract relation page IDs (handled differently from standard scalars)
+            if (scalar.moxnType === 'page_ref') {
+                const refs = (propValue.relation ?? [])
+                    .map((r) => normalizeId(r.id))
+                    .filter(Boolean);
+                if (refs.length > 0) {
+                    scalarValues.set(propName, {
+                        columnName: propName,
+                        moxnType: 'page_ref',
+                        textValue: JSON.stringify(refs.map((id) => `notion:${id}`)),
+                    });
+                }
+            }
+            else {
+                const extracted = extractScalarValue(propValue, scalar);
+                if (extracted) {
+                    scalarValues.set(propName, extracted);
+                }
             }
             continue;
         }

package/dist/sources/notion-references.d.ts

@@ -10,6 +10,7 @@
 import type { SectionInput } from '../types.js';
 export interface NotionIdMapping {
     notionIdToKbPath: Map<string, string>;
+    notionIdToTitle?: Map<string, string>;
 }
 export interface ExtractedReference {
     sectionIndex: number;

package/dist/sources/notion-references.js

@@ -125,17 +125,19 @@ export function resolveNotionReferences(sections, mapping) {
             text = text.replace(RELATION_REF_RE, (_match, rawId) => {
                 const nid = normalizeId(rawId);
                 const kbPath = mapping.notionIdToKbPath.get(nid);
+                const title = mapping.notionIdToTitle?.get(nid);
                 if (kbPath) {
+                    const displayText = title || kbPath;
                     references.push({
                         sectionIndex,
                         targetNotionId: nid,
                         targetKbPath: kbPath,
-                        displayText: kbPath,
+                        displayText,
                     });
-                    return `[${kbPath}](${kbPath})`;
+                    return `[${displayText}](${kbPath})`;
                 }
-                // Unresolved — keep the ID
-                return nid;
+                // Unresolved — show title if available, otherwise keep the ID
+                return title || nid;
             });
             return { blockType: 'text', text };
         });
@@ -151,9 +153,10 @@ export function resolveRelationIds(value, mapping) {
     return value.replace(RELATION_REF_RE, (_match, rawId) => {
         const nid = normalizeId(rawId);
         const kbPath = mapping.notionIdToKbPath.get(nid);
+        const title = mapping.notionIdToTitle?.get(nid);
         if (kbPath) {
-            return `[${kbPath}](${kbPath})`;
+            return `[${title || kbPath}](${kbPath})`;
         }
-        return nid;
+        return title || nid;
     });
 }

package/dist/sources/notion.d.ts

@@ -9,6 +9,7 @@
  */
 import type { ExtractedDocument } from '../types.js';
 import { MigrationSource, type SourceConfig } from './base.js';
+import { NotionApiClient } from './notion-api.js';
 import type { NotionPage, NotionDatabase } from './notion-api.js';
 import { type PagePathMap } from './notion-blocks.js';
 import { type ParsedDatabaseSchema } from './notion-databases.js';
@@ -48,6 +49,7 @@ export declare class NotionSource extends MigrationSource<NotionSourceConfig> {
     private pageTree;
     private allPages;
     private pagePathMap;
+    private pageTitleMap;
     private databases;
     private databaseEntryPageIds;
     private _documentCount;
@@ -59,6 +61,8 @@ export declare class NotionSource extends MigrationSource<NotionSourceConfig> {
     private _unsupportedBlocks;
     /** Map of Notion database ID → KB database ID, set before extraction. */
     private _databaseIdMap;
+    /** Collects inline databases encountered during extraction but not in databaseIdMap. */
+    private _unresolvedChildDatabases;
     constructor(config: NotionSourceConfig);
     /**
      * Set the database ID map (Notion DB ID → KB DB ID).
@@ -76,6 +80,18 @@ export declare class NotionSource extends MigrationSource<NotionSourceConfig> {
      */
     getDatabaseImports(): NotionDatabaseImportInfo[];
     extract(): AsyncGenerator<ExtractedDocument, void, unknown>;
+    /** Get extraction stats for reconciling discovered vs extracted counts. */
+    getExtractionStats(): {
+        discovered: number;
+        extracted: number;
+        skippedEmpty: string[];
+        skippedNoContent: string[];
+        errors: string[];
+    };
+    /** Get unresolved inline databases found during extraction. */
+    getUnresolvedInlineDatabases(): Map<string, string>;
+    /** Expose the Notion API client (for fetching inline DB schemas). */
+    getNotionApiClient(): NotionApiClient;
     /** Clean up temp files after migration completes. */
     cleanup(): Promise<void>;
     private buildPageTreeInternal;
@@ -96,6 +112,7 @@ export interface PageTreeResult {
     tree: PageTreeNode[];
     allPages: PageTreeNode[];
     pagePathMap: PagePathMap;
+    pageTitleMap: Map<string, string>;
     databaseEntryPageIds: Set<string>;
 }
 /**

package/dist/sources/notion.js

@@ -24,6 +24,7 @@ export class NotionSource extends MigrationSource {
     pageTree = [];
     allPages = []; // flat list, depth-first order
     pagePathMap = new Map();
+    pageTitleMap = new Map();
     databases = [];
     databaseEntryPageIds = new Set();
     _documentCount = 0;
@@ -36,6 +37,8 @@ export class NotionSource extends MigrationSource {
     _unsupportedBlocks = new Map();
     /** Map of Notion database ID → KB database ID, set before extraction. */
     _databaseIdMap = new Map();
+    /** Collects inline databases encountered during extraction but not in databaseIdMap. */
+    _unresolvedChildDatabases = new Map();
     constructor(config) {
         super(config);
         this.client = new NotionApiClient(config.token);
@@ -156,6 +159,7 @@ export class NotionSource extends MigrationSource {
         this._skippedNoContent = [];
         this._extractionErrors = [];
         this._unsupportedBlocks = new Map();
+        this._unresolvedChildDatabases = new Map();
         let yielded = 0;
         // Walk pages depth-first
         for (const node of this.allPages) {
@@ -224,6 +228,27 @@ export class NotionSource extends MigrationSource {
             console.log(`  ⚠ Count mismatch: expected ${expectedYield} (${this._documentCount} - ${totalSkipped} skipped) but extracted ${yielded}`);
         }
     }
+    /** Get extraction stats for reconciling discovered vs extracted counts. */
+    getExtractionStats() {
+        const totalSkipped = this._skippedEmpty.length +
+            this._skippedNoContent.length +
+            this._extractionErrors.length;
+        return {
+            discovered: this._documentCount,
+            extracted: this._documentCount - totalSkipped,
+            skippedEmpty: [...this._skippedEmpty],
+            skippedNoContent: [...this._skippedNoContent],
+            errors: [...this._extractionErrors],
+        };
+    }
+    /** Get unresolved inline databases found during extraction. */
+    getUnresolvedInlineDatabases() {
+        return new Map(this._unresolvedChildDatabases);
+    }
+    /** Expose the Notion API client (for fetching inline DB schemas). */
+    getNotionApiClient() {
+        return this.client;
+    }
     /** Clean up temp files after migration completes. */
     async cleanup() {
         await this.mediaDownloader.cleanup();
@@ -240,6 +265,7 @@ export class NotionSource extends MigrationSource {
         this.pageTree = result.tree;
         this.allPages = result.allPages;
         this.pagePathMap = result.pagePathMap;
+        this.pageTitleMap = result.pageTitleMap;
         this.databaseEntryPageIds = result.databaseEntryPageIds;
     }
     // ============================================
@@ -287,11 +313,12 @@ export class NotionSource extends MigrationSource {
             let sections = await blocksToSections(blocks, this.client, this.pagePathMap, {
                 databaseIdMap: this._databaseIdMap.size > 0 ? this._databaseIdMap : undefined,
                 unsupportedBlocks: this._unsupportedBlocks,
+                unresolvedChildDatabases: this._unresolvedChildDatabases,
             });
             // Download Notion-hosted media files
             sections = await this.downloadSectionMedia(sections);
             // Resolve cross-references
-            const { sections: resolvedSections, references } = resolveNotionReferences(sections, { notionIdToKbPath: this.pagePathMap });
+            const { sections: resolvedSections, references } = resolveNotionReferences(sections, { notionIdToKbPath: this.pagePathMap, notionIdToTitle: this.pageTitleMap });
             sections = resolvedSections;
             if (sections.length === 0) {
                 this._skippedNoContent.push(node.title);
@@ -333,13 +360,14 @@ export class NotionSource extends MigrationSource {
                 const contentSections = await blocksToSections(blocks, this.client, this.pagePathMap, {
                     databaseIdMap: this._databaseIdMap.size > 0 ? this._databaseIdMap : undefined,
                     unsupportedBlocks: this._unsupportedBlocks,
+                    unresolvedChildDatabases: this._unresolvedChildDatabases,
                 });
                 sections.push(...contentSections);
             }
             // Download media
             let processedSections = await this.downloadSectionMedia(sections);
             // Resolve cross-references
-            const { sections: resolvedSections, references } = resolveNotionReferences(processedSections, { notionIdToKbPath: this.pagePathMap });
+            const { sections: resolvedSections, references } = resolveNotionReferences(processedSections, { notionIdToKbPath: this.pagePathMap, notionIdToTitle: this.pageTitleMap });
             processedSections = resolvedSections;
             const nid = normalizeId(entry.id);
             const kbPath = this.pagePathMap.get(nid) ?? slug;
@@ -392,6 +420,7 @@ export class NotionSource extends MigrationSource {
  */
 export function buildPageTree(pages, options) {
     const pagePathMap = new Map();
+    const pageTitleMap = new Map();
     const databaseEntryPageIds = new Set();
     const tree = [];
     const allPages = [];
@@ -493,7 +522,11 @@ export function buildPageTree(pages, options) {
     }
     // Build tree recursively
     const buildNode = (page, parentPath, depth, siblingSlugCounts) => {
-        if (options?.maxDepth !== undefined && depth > options.maxDepth) {
+        const nid = normalizeId(page.id);
+        const isDatabaseSubtree = syntheticDatabaseIds.has(nid) || databaseEntryPageIds.has(nid);
+        if (options?.maxDepth !== undefined &&
+            depth > options.maxDepth &&
+            !isDatabaseSubtree) {
             return null;
         }
         const title = getPageTitle(page);
@@ -505,7 +538,6 @@ export function buildPageTree(pages, options) {
             slug = `${slug}-${existing + 1}`;
         }
         const kbPath = parentPath ? `${parentPath}/${slug}` : slug;
-        const nid = normalizeId(page.id);
         const isDatabaseEntry = databaseEntryPageIds.has(nid);
         const node = {
             page,
@@ -517,8 +549,9 @@ export function buildPageTree(pages, options) {
             parentDatabaseId: page.parent.type === 'database_id' ? page.parent.database_id : undefined,
             children: [],
         };
-        // Register in path map
+        // Register in path map and title map
         pagePathMap.set(nid, kbPath);
+        pageTitleMap.set(nid, title);
         // Process children
         const childPages = childrenByParent.get(nid) ?? [];
         const childSlugCounts = new Map();
@@ -546,7 +579,7 @@ export function buildPageTree(pages, options) {
         }
     };
     flatten(tree);
-    return { tree, allPages, pagePathMap, databaseEntryPageIds };
+    return { tree, allPages, pagePathMap, pageTitleMap, databaseEntryPageIds };
 }
 /** Extract the parent page ID from a Notion page's parent field. */
 function getParentPageId(page) {

package/dist/types.d.ts

@@ -172,6 +172,10 @@ export interface MigrationLog {
         skipped: number;
         failed: number;
         duration: number;
+        /** Upper-bound page count from discovery (before extraction skips). */
+        discovered?: number;
+        /** Pages skipped during extraction (empty, no content, errors). */
+        skippedDuringExtraction?: number;
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.24",
+  "version": "0.4.26",
   "description": "Migration tool for importing documents into Moxn Knowledge Base from local files, Notion, Google Docs, and more",
   "type": "module",
   "main": "dist/index.js",