diff --git a/deploy/postgres/goose/00029_2026-09-13-freeform-client-key.sql b/deploy/postgres/goose/00029_2026-09-13-freeform-client-key.sql
new file mode 100644
index 00000000..2a0ca1b4
--- /dev/null
+++ b/deploy/postgres/goose/00029_2026-09-13-freeform-client-key.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- 2026-09-13 freeform upload registration: formal client_key for idempotent server fact-source create
+-- Schema 28 → 29
+
+ALTER TABLE freeform_documents
+    ADD COLUMN IF NOT EXISTS client_key VARCHAR(128) NULL;
+
+COMMENT ON COLUMN freeform_documents.client_key IS
+    'Client-supplied idempotency key for direct create (e.g. upload batch id); NULL for message-derived docs';
+
+-- Same owner cannot register the same client_key twice while the doc is alive.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_freeform_owner_client_key
+    ON freeform_documents (owner_user_id, client_key)
+    WHERE is_deleted = FALSE AND client_key IS NOT NULL AND length(trim(client_key)) > 0;
+
+-- +goose Down
+DROP INDEX IF EXISTS uq_freeform_owner_client_key;
+ALTER TABLE freeform_documents DROP COLUMN IF EXISTS client_key;