[docs] Add .env.example files to extensions and dashboard

[matthallett1]

Summary

Closes #17.

• Added .env.example to all 6 extensions documenting the 3 required env vars
• Added .env.example to the dashboard with its 4 vars + symlink tip
• Hardened .gitignore: added .env.local, .env.*.local, and deno.lock

What's in each .env.example

Extensions (all identical):

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
MCP_ACCESS_KEY=your-mcp-access-key

Dashboard:

MCP_URL=https://your-project.supabase.co/functions/v1/open-brain-mcp
MCP_KEY=your-mcp-access-key
PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Test plan

• Verified .env.example files are tracked (not gitignored)
• Verified .env.local and deno.lock are gitignored
• No secrets in any committed file

🤖 Generated with Claude Code

[github-actions]

OB1 Automated Review

This PR modifies docs or repo governance files. Contribution checks skipped.

✅ No issues found.

[justfinethanku]

Code Review: PR #81

Summary: This PR makes significant changes beyond what the title and description indicate. While the stated goal (adding .env.example files) is valuable, the PR also includes:

1. ✅ Added .env.example files to all extensions and dashboard (as stated)
2. ✅ Hardened .gitignore with .env.local and .env.*.local patterns (as stated)
3. ⚠️ Removed DEFAULT_USER_ID requirement from all extensions - making user_id an explicit tool parameter instead (NOT mentioned in description)
4. ⚠️ Removed visual formatting requirements from CONTRIBUTING.md - deleted the entire "Visual Formatting Requirements" section including step badges, verification checkpoints, collapsible SQL blocks, numbered commands, and GRANT step requirements (NOT mentioned in description)
5. ⚠️ Large changes to life-engine and life-engine-video recipes - appears to be a complete rewrite/restructuring (NOT mentioned in description)
6. ⚠️ Changes to multiple other files - README.md, docs/01-getting-started.md, extensions/_template/README.md, and all extension code/schemas (NOT mentioned in description)

What's Good

• The .env.example files are well-structured with clear placeholder values
• No credentials or secrets detected - all values are properly placeholder text
• The .gitignore changes are sensible and safe
• PR title format follows the [category] pattern correctly

Issues

1. Scope Mismatch (Critical)
The PR title says "Add .env.example files to extensions and dashboard" but the diff shows 36 changed files including major architectural changes to extensions (removing DEFAULT_USER_ID), documentation standards (removing formatting requirements), and recipe content (life-engine rewrite). This violates the principle of focused, reviewable PRs.

2. Missing Context in Description
The PR description makes no mention of:

• Why DEFAULT_USER_ID is being removed from extensions
• Why visual formatting requirements are being removed from CONTRIBUTING.md
• What changed in the life-engine recipes and why
• The impact on existing extension users who may have DEFAULT_USER_ID configured

3. Potential Breaking Changes
Removing DEFAULT_USER_ID from extensions appears to be a breaking change. Users with existing setups may have this configured via supabase secrets set. The new approach requires user_id to be passed as a tool parameter, which changes the user interface of all extension tools.

4. Documentation Standards Removal
The deleted "Visual Formatting Requirements" section from CONTRIBUTING.md was substantial (60+ lines) and included important patterns like:

• GRANT step requirements (critical for Supabase permissions)
• Step badges and verification checkpoints (user experience)
• Numbered commands and collapsible SQL blocks (readability)

If these are intentionally being removed, the PR should explain why and ensure existing extensions that follow these patterns are still acceptable.

Recommendations

Option 1: Split into focused PRs

• PR #81a: Add .env.example files and .gitignore hardening (ready to merge as-is)
• PR #81b: Remove DEFAULT_USER_ID from extensions (needs discussion about breaking changes and migration path)
• PR #81c: Update CONTRIBUTING.md formatting requirements (needs explanation for why these are being removed)
• PR #81d: Life Engine recipe updates (separate from infrastructure changes)

Option 2: Update this PR with full context
Expand the PR description to explain:

• The rationale for removing DEFAULT_USER_ID
• Migration path for existing users
• Why formatting requirements are being relaxed
• What changed in life-engine and why it's bundled here
• Add a breaking changes section

Notes

• This is Matt Hallett's PR (#81) - he's a trusted collaborator, so the code quality is not in question
• The .env.example files themselves are excellent and solve issue #17 cleanly
• The .gitignore changes are sensible
• No SQL safety issues (no DROP/TRUNCATE/unqualified DELETE)
• No binary blobs or large files

Verdict: Significant changes needed

The .env.example additions are ready to merge, but the PR needs to either be split into focused changes or have its description substantially expanded to explain the scope and rationale for all changes. The DEFAULT_USER_ID removal in particular needs migration guidance.

[matthallett1]

@claude review this PR

[github-actions]

Claude finished @matthallett1's task in 2m 30s —— View job

---

PR Review: [docs] Add .env.example files to extensions and dashboard

• Gather context and read changed files
• Review .env.example files and .gitignore changes
• Address existing review discussion
• Post final review

---

Summary

This PR is exactly what it says: 8 files, 49 additions, 0 deletions — .env.example files for all 6 extensions and the dashboard, plus three .gitignore additions. The scope matches the title and description precisely.

Note on the previous review: @justfinethanku's review describes 36 changed files with major architectural changes (removing DEFAULT_USER_ID, rewriting CONTRIBUTING.md, etc.). Those changes do not exist in this PR. The single commit on this branch touches only the 8 files listed — I confirmed this by inspecting the commit directly. The previous review may have been run against a stale or incorrect diff. It should not block this PR.

---

What's Good

Extension .env.example files — all 6 are identical and correct:

# These are set automatically by Supabase when you deploy an Edge Function.
# You only need to set MCP_ACCESS_KEY manually.

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
MCP_ACCESS_KEY=your-mcp-access-key

The comment is excellent — it accurately reflects Supabase Edge Function behavior and prevents the common mistake of manually setting all three vars. The env var names match what the extension code actually reads (Deno.env.get("MCP_ACCESS_KEY"), etc.).

Dashboard .env.example — well-structured:

MCP_URL=https://your-project.supabase.co/functions/v1/open-brain-mcp
MCP_KEY=your-mcp-access-key
PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_ANON_KEY=your-anon-key

The PUBLIC_ prefix convention is correct for SvelteKit. The symlink tip is a nice touch for users who work across multiple dashboards.

.gitignore additions:

• .env.local and .env.*.local — critical, since the .env.example instructs users to copy to .env.local; without this, they'd accidentally commit secrets
• deno.lock — reasonable for a community contributions repo where extensions are deployed independently

No secrets. No destructive SQL. No binary blobs. No core schema modifications. No local MCP server patterns.

---

Minor Notes

1. deno.lock ignoring is a minor trade-off. Committing lock files gives reproducible builds; ignoring them means each deployer resolves dependencies fresh. For a community-contributions repo with independently deployed Edge Functions, ignoring is the pragmatic choice — but worth documenting somewhere (a comment in .gitignore would suffice). This is not a blocker.

2. The symlink tip path ../../.env.local in the dashboard .env.example correctly resolves to the repo root from dashboards/open-brain-dashboard/. No issue, just noting it's been verified.

---

Verdict

This PR is ready to merge. It's a clean, focused, well-executed documentation improvement that closes #17. The .env.example files are accurate, the .gitignore additions are correct, and there are no safety issues. The previous review's concerns do not apply to the actual changes in this PR.

[github-actions]

Claude finished @matthallett1's task in 2m 14s —— View job

---

PR Review: [docs] Add .env.example files to extensions and dashboard

• Gather context and read changed files
• Review .env.example files
• Review server/index.ts changes (not mentioned in PR description)
• Post final review

---

Summary

This PR has two distinct changes bundled together: a clean, ready-to-merge docs improvement and an unmentioned functional change to server/index.ts. I'll address both.

---

The .env.example Files — Ready to Merge ✅

All 6 extension files and the dashboard update are correct and well-executed:

Extension files (e.g. extensions/family-calendar/.env.example):

# These are set automatically by Supabase when you deploy an Edge Function.
# You only need to set MCP_ACCESS_KEY manually.

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
MCP_ACCESS_KEY=your-mcp-access-key

The comment is the best part — it prevents the common mistake of manually setting all three vars when Supabase injects two of them automatically. The var names match what the extension code actually reads.

Dashboard addition — the symlink tip at ../../.env.local resolves correctly from dashboards/open-brain-dashboard/ to the repo root. Nice UX touch.

.gitignore — These changes are already in main (the diff confirms no .gitignore change between this branch and main). They shipped as intended.

No credentials. No destructive SQL. No core schema modifications. No local MCP server patterns.

---

server/index.ts — Needs Discussion ⚠️

Commit 38bc133 ("feat: use content fingerprint dedup in capture_thought") changes capture_thought from a direct insert to a two-step RPC pattern. This is not mentioned in the PR description or title, and the [docs] category prefix is incorrect for it.

What changed (server/index.ts:319-342):

• Old: supabase.from("thoughts").insert(...) — single atomic operation
• New: supabase.rpc("upsert_thought", ...) followed by a separate .update({ embedding }) on the returned ID

Concerns:

1. Undeclared prerequisite. The upsert_thought RPC is defined in primitives/content-fingerprint-dedup/README.md as an optional manual setup step. Users must run SQL to create it. Anyone running the MCP server without this primitive applied will get a runtime error every time capture_thought is called — with no helpful message explaining the missing dependency.

2. Non-atomic embedding update. The upsert and embedding write are now two separate database calls. If the second call fails (embError), the thought is stored without a vector embedding — it will never appear in semantic search results. The original single-insert was atomic; this pattern introduces a window for silent data degradation. Fix this →

3. Scope and category mismatch. A [docs] PR shouldn't contain a feat: commit that changes runtime behavior of the MCP server. This makes the PR harder to review and harder to revert if issues surface.

Recommendation: Pull 38bc133 out into its own [server] or [feat] PR that:

• Documents the upsert_thought prerequisite step prominently (or adds a fallback if the RPC doesn't exist)
• Addresses the non-atomic embedding write
• Is correctly categorized

The .env.example portion can merge immediately without that commit.

---

Verdict

The .env.example additions are ready to merge. The server/index.ts change bundled in this PR needs its own PR with a clearer scope, documented prerequisite, and a fix for the non-atomic embedding write. If you'd like the quickest path forward, drop commit 38bc133 from this branch and open a follow-up PR for the dedup integration.