From fce2f2d941aefb7ecb24f3e31e8fbab3f302e808 Mon Sep 17 00:00:00 2001
From: Eli Fayerman <fayerman@gmail.com>
Date: Mon, 4 May 2026 20:09:05 -0400
Subject: [PATCH] docs: add safe local testing guide

---
 README.md                   |  3 ++
 docs/safe-local-testing.md  | 89 +++++++++++++++++++++++++++++++++++++
 frontend/.env.local.example |  1 -
 3 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 docs/safe-local-testing.md

diff --git a/README.md b/README.md
index 37cd7258..e21ae70f 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,9 @@ cp backend/.env.example backend/.env
 cp frontend/.env.local.example frontend/.env.local
 ```
 
+Before adding real secrets or uploading documents, read
+[`docs/safe-local-testing.md`](docs/safe-local-testing.md).
+
 Run `backend/migrations/000_one_shot_schema.sql` in the Supabase SQL editor for a fresh database.
 
 Start the backend:
diff --git a/docs/safe-local-testing.md b/docs/safe-local-testing.md
new file mode 100644
index 00000000..877a629b
--- /dev/null
+++ b/docs/safe-local-testing.md
@@ -0,0 +1,89 @@
+# Safe Local Testing
+
+Mike is a young open-source legal AI project. Until you have reviewed your
+deployment and data flows, test it with disposable infrastructure and synthetic
+documents only.
+
+## Use Disposable Test Resources
+
+Create separate test resources for Mike:
+
+- a throwaway Supabase project
+- a throwaway S3-compatible storage bucket, such as Cloudflare R2
+- disposable model-provider API keys with low spending limits
+- a test email account
+
+Do not use production Supabase projects, production storage buckets, firm API
+keys, or real client documents for initial testing.
+
+## Keep Secrets Out of the Frontend
+
+Only variables prefixed with `NEXT_PUBLIC_` should be assumed safe to expose to
+the browser. Service-role keys and model-provider keys should stay server-side.
+
+For frontend testing, `frontend/.env.local` should normally contain only:
+
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your-supabase-anon-key
+NEXT_PUBLIC_API_BASE_URL=http://localhost:3001
+```
+
+Keep the Supabase service-role key in `backend/.env` only:
+
+```env
+SUPABASE_SECRET_KEY=your-supabase-service-role-key
+```
+
+Model-provider keys such as `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and
+`OPENROUTER_API_KEY` should also stay in `backend/.env`.
+
+## Test With Synthetic Documents
+
+Use fake or public sample documents when testing:
+
+- synthetic NDAs
+- sample contracts
+- public court documents
+- dummy PDF/DOCX files
+
+Do not upload privileged, confidential, client, matter, personnel, or firm
+knowledge-management material until you are comfortable with the deployment's
+storage, logging, deletion, and model-provider behavior.
+
+## Confirm Environment Files Are Not Tracked
+
+Before running or committing changes, check:
+
+```bash
+git status --short
+```
+
+Stop if `.env`, `.env.local`, or any file containing secrets appears in the
+output.
+
+## Start With Non-LLM Flows
+
+If you do not want to use model-provider keys yet, use dummy provider values and
+test only the non-LLM flows first:
+
+- account creation against a test Supabase project
+- project creation
+- file upload with synthetic documents
+- folder organization
+- document deletion
+
+Then add one disposable, capped model-provider key and test assistant behavior
+with synthetic documents.
+
+## Clean Up After Testing
+
+After testing, delete:
+
+- uploaded objects from the storage bucket
+- test Supabase rows or the whole test Supabase project
+- disposable model-provider keys
+- local `.env` files that contain secrets
+
+For legal-document workflows, deletion semantics matter. Verify that your
+storage bucket no longer contains test document objects after delete flows.
diff --git a/frontend/.env.local.example b/frontend/.env.local.example
index 4e00a720..c0ceb714 100644
--- a/frontend/.env.local.example
+++ b/frontend/.env.local.example
@@ -1,4 +1,3 @@
 NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=your-supabase-anon-key
-SUPABASE_SECRET_KEY=your-supabase-service-role-key
 NEXT_PUBLIC_API_BASE_URL=http://localhost:3001