learning_ai_notes/docs/IMPORT_EXPORT_READINESS.md

NoteLett Import And Export Readiness

Date: May 5, 2026

Export Scope

Note export is production-ready for authenticated users through GET /api/notes/export.

Supported formats:

• format=json returns notelett.notes.export.v1 with stable metadata, deterministic field order, sorted note records, and storage-only fields omitted.
• format=markdown returns readable Markdown with export metadata and one section per note.

Supported filters:

• all notes for the authenticated user
• notes scoped to a single workspaceId

The backend pages through the notes repository in batches of 100 so exports are not silently truncated at the API list limit. Exported records are scoped by authenticated user and productId: notelett.

Import Deferral

Import is intentionally deferred for release 1 because the current product has encrypted note bodies, workspace membership boundaries, version history, agent action audit trails, and artifact references. Import needs an explicit conflict and ownership model before it can be safe.

Acceptance criteria before enabling import:

• Accept only notelett.notes.export.v1 JSON.
• Validate every note with Zod before persistence.
• Require an authenticated writer and explicit target workspace ownership or membership.
• Never trust exported createdBy, updatedBy, workspaceId, or userId without remapping to the current account/workspace.
• Support dry-run validation that reports create/update/skip counts.
• Define conflict handling for duplicate note IDs, title collisions, tags, links, and source URIs.
• Write note versions and agent audit entries for imported updates.
• Keep field encryption enabled for imported body content.
• Add backend tests for malformed import, cross-user export replay, workspace remap, conflict decisions, and encrypted storage.
• Add web import UX only after dry-run and conflict behavior are available.