[recipes] Brain backup and export

docs/01-getting-started.md

@@ -239,9 +239,7 @@ You'll land on the **"Publishable and secret API keys"** tab. Copy these into yo
 - 🔖 **Secret key** — Scroll down to the **"Secret keys"** section on the same page. You'll see a `default` key. Click the copy button to copy it. (You can also click **"+ New secret key"** to create a dedicated one named `open-brain` — this makes it easier to revoke later without affecting other services, but using the default is fine too.)
 
 > [!WARNING]
-> Treat the Secret key like a password. Anyone with it has full access to your data. The "Publishable key" at the top of the page is safe to expose publicly — you don't need it for this setup.
->
-> You may also see a **"Legacy anon, service_role API keys"** tab — those are the old-style JWT keys. You don't need them. Everything in this guide uses the new key format.
+> Treat the Secret key like a password. Anyone with it has full access to your data. The "Publishable key" at the top of the page is safe to expose publicly — you don't need it for this setup. You may also see a **"Legacy anon, service_role API keys"** tab — those are the old-style JWT keys. You don't need them. Everything in this guide uses the new key format.
 
 ✅ **Done when:** Your credential tracker has both **Project URL** and **Secret key** filled in.
 
@@ -289,6 +287,8 @@ Copy the output — it'll look something like `a3f8b2c1d4e5...` (64 characters).
 > [!WARNING]
 > Copy and paste the command for **your operating system only**. The Mac command won't work on Windows and vice versa.
 
+<!-- -->
+
 > [!IMPORTANT]
 > This is your **one access key for all of Open Brain** — core setup and every extension you add later. Save it somewhere permanent. Never generate a new one unless you want to replace it for ALL deployed functions.
 
@@ -419,9 +419,12 @@ supabase secrets set OPENROUTER_API_KEY=your-openrouter-key-here
 > [!CAUTION]
 > Make sure the access key you set here **exactly matches** what you saved in your credential tracker. If they don't match, you'll get 401 errors when connecting your AI.
 
+<!-- -->
+
 > **If you ever rotate your OpenRouter key:** you must re-run the `supabase secrets set` command above with the new key, AND update any local `.env` files that reference it. The edge function reads from Supabase secrets at runtime — updating the key on openrouter.ai alone won't propagate here. See the [FAQ on key rotation](03-faq.md#api-key-rotation) for the full checklist.
 
 ### Create the Function
+
 ![6.6](https://img.shields.io/badge/6.6-Download_the_Server_Files-555?style=for-the-badge&labelColor=1E88E5)
 
 Three commands, run them one at a time in order:

docs/03-faq.md

@@ -173,6 +173,7 @@ When you generate a new key on openrouter.ai/keys, the old key is revoked immedi
 **Places your OpenRouter key lives (update ALL of them):**
 
 1. **Supabase Edge Function secrets** — This is the most common one to miss. Your MCP server reads the key from here at runtime.
+
    ```bash
    supabase secrets set OPENROUTER_API_KEY=sk-or-v1-your-new-key
    ```

docs/05-tool-audit.md

@@ -81,6 +81,7 @@ Once you've identified bloat, here are the patterns for consolidating.
 Instead of 5 separate tools per table, expose one tool with an `action` parameter:
 
 **Before (5 tools):**
+
 ```
 create_recipe
 get_recipe
@@ -90,6 +91,7 @@ list_recipes
 ```
 
 **After (1 tool):**
+
 ```
 manage_recipe
   action: "create" | "read" | "update" | "delete" | "list"
@@ -107,6 +109,7 @@ manage_recipe
 A gentler consolidation that preserves clear intent:
 
 **Before (5 tools):**
+
 ```
 create_recipe
 get_recipe
@@ -116,6 +119,7 @@ search_recipes
 ```
 
 **After (2 tools):**
+
 ```
 save_recipe       — creates or updates (upsert pattern)
 query_recipes      — search, filter, get by ID, list all
@@ -132,6 +136,7 @@ This maps to how people actually talk to their AI: "save this" or "find that." T
 For tables with similar schemas (all your Open Brain extension tables follow the same `user_id` + timestamps + domain fields pattern), you can go further:
 
 **Before (20+ tools across 4 extensions):**
+
 ```
 add_household_item, search_household_items, get_item_details,
 add_vendor, list_vendors,
@@ -140,6 +145,7 @@ search_maintenance_history, add_family_member, ...
 ```
 
 **After (2–3 tools):**
+
 ```
 save_entity
   entity_type: "household_item" | "vendor" | "maintenance_task" | ...
@@ -177,6 +183,7 @@ Merging tools reduces count within a server. Scoping splits tools across servers
 Most Open Brain users' workflows fall into three modes:
 
 #### Capture server (write-heavy)
+
 **When you use it:** Quick capture moments — jotting down a thought, logging a contact interaction, saving a recipe.
 
 **Tools to include:**
@@ -189,6 +196,7 @@ Most Open Brain users' workflows fall into three modes:
 **Context cost:** ~5–8 tools, ~1,500–3,000 tokens.
 
 #### Query server (read-heavy)
+
 **When you use it:** Research, recall, weekly reviews, planning sessions — any time you're pulling information out rather than putting it in.
 
 **Tools to include:**
@@ -202,6 +210,7 @@ Most Open Brain users' workflows fall into three modes:
 **Context cost:** ~8–12 tools, ~3,000–5,000 tokens.
 
 #### Admin server (rarely used)
+
 **When you use it:** Occasional maintenance — bulk updates, deletions, schema changes, data cleanup.
 
 **Tools to include:**

integrations/slack-capture/README.md

@@ -240,6 +240,8 @@ Replace the values with:
 
 > SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are automatically available inside Edge Functions — you don't need to set them.
 
+<!-- -->
+
 > **If you ever rotate your OpenRouter key:** you must re-run `supabase secrets set OPENROUTER_API_KEY=...` with the new key. This Edge Function reads the key from Supabase secrets at runtime — updating it on openrouter.ai alone won't propagate here. See the [FAQ on key rotation](../../docs/03-faq.md#api-key-rotation) for the full checklist.
 
 ### Deploy
@@ -342,6 +344,8 @@ You now have a Slack channel that acts as a direct write path into your Open Bra
 
 This is one of many possible capture interfaces. Your Open Brain MCP server also includes a `capture_thought` tool, which means any MCP-connected AI (Claude Desktop, ChatGPT, Claude Code, Cursor) can write directly to your brain without switching apps. Slack is just the dedicated inbox.
 
+Before adding more MCP-powered capture paths, review the [MCP Tool Audit & Optimization Guide](../../docs/05-tool-audit.md) so your tool surface stays intentional and manageable.
+
 ---
 
 *Built by Nate B. Jones — part of the [Open Brain project](https://github.com/NateBJones-Projects/OB1)*

recipes/brain-backup/README.md

@@ -0,0 +1,95 @@
+# Brain Backup and Export
+
+> Export all Open Brain tables to local JSON files for safekeeping.
+
+## What It Does
+
+Paginates through every Open Brain Supabase table (1 000 rows per request) and writes each one to a dated JSON file inside a local `backup/` directory. Prints live progress and a summary table so you know exactly what was saved.
+
+## Prerequisites
+
+- Working Open Brain setup ([guide](../../docs/01-getting-started.md))
+- Node.js 18+ installed
+- A `.env.local` file in the recipe directory (or its parent) containing `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`
+
+## Credential Tracker
+
+Copy this block into a text editor and fill it in as you go.
+
+```text
+BRAIN BACKUP -- CREDENTIAL TRACKER
+--------------------------------------
+
+FROM YOUR OPEN BRAIN SETUP
+  Project URL:           ____________
+  Service-role key:      ____________
+
+--------------------------------------
+```
+
+## Steps
+
+1. **Copy the script into your project.** Place `backup-brain.mjs` wherever is convenient, or run it directly from this recipe folder.
+
+2. **Create a `.env.local` file** next to the script (or one directory above it) with your Supabase credentials:
+
+   ```text
+   SUPABASE_URL=https://<your-project-ref>.supabase.co
+   SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
+   ```
+
+3. **Run the backup:**
+
+   ```bash
+   node backup-brain.mjs
+   ```
+
+   The script will read `.env.local` automatically. Alternatively, you can export the variables first:
+
+   ```bash
+   export SUPABASE_URL=https://<your-project-ref>.supabase.co
+   export SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
+   node backup-brain.mjs
+   ```
+
+4. **Check the output.** A `backup/` directory will be created containing one JSON file per table, each named `<table>-YYYY-MM-DD.json`.
+
+## Expected Outcome
+
+After running the script you should see live row counts for each table followed by a summary like this:
+
+```
+Open Brain Backup — 2026-04-06
+Target: /path/to/backup
+
+  thoughts: 1200 rows (1.4 MB)
+  entities: 340 rows (98.2 KB)
+  ...
+
+--- Backup Summary ---
+Date:  2026-04-06
+Dir:   /path/to/backup
+
+Table               Rows      Size
+--------------------------------------
+thoughts            1200    1.4 MB
+entities             340   98.2 KB
+...
+--------------------------------------
+TOTAL               1842    1.7 MB
+
+Done. 7/7 tables exported successfully.
+```
+
+The `backup/` directory will contain one JSON file per table. Each file is a valid JSON array that can be re-imported or queried with any JSON tool.
+
+## Troubleshooting
+
+**Issue: "SUPABASE_URL not found" error**
+Solution: Make sure `.env.local` exists next to the script (or one directory up) and contains a line starting with `SUPABASE_URL=`.
+
+**Issue: "SUPABASE_SERVICE_ROLE_KEY not found" error**
+Solution: Add your service-role key to `.env.local`. You can find it in your Supabase dashboard under Settings > API.
+
+**Issue: "PostgREST error 401" or "PostgREST error 403"**
+Solution: Your service-role key may be expired or incorrect. Regenerate it in the Supabase dashboard and update `.env.local`.