[repo] Sweep fix-now backlog issues

README.md

@@ -83,7 +83,7 @@ Standalone capabilities that make your Open Brain smarter.
 | ------ | ------------ | ----------- |
 | [Auto-Capture Protocol](recipes/auto-capture/) | Stores ACT NOW items and session summaries in Open Brain at session close using the reusable Auto-Capture skill | [@jaredirish](https://github.com/jaredirish) |
 | [Panning for Gold](recipes/panning-for-gold/) | Mine brain dumps and voice transcripts for actionable ideas — battle-tested across 13+ sessions | [@jaredirish](https://github.com/jaredirish) |
-| [Claudeception](recipes/claudeception/) | Self-improving system that creates new skills from work sessions — skills that create other skills | [@jaredirish](https://github.com/jaredirish) |
+| [Aiception (formerly Claudeception)](recipes/claudeception/) | Self-improving system that creates new skills from work sessions — skills that create other skills | [@jaredirish](https://github.com/jaredirish) |
 | [Schema-Aware Routing](recipes/schema-aware-routing/) | LLM-powered routing that distributes unstructured text across multiple database tables | [@claydunker-yalc](https://github.com/claydunker-yalc) |
 | [Fingerprint Dedup Backfill](recipes/fingerprint-dedup-backfill/) | Backfill content fingerprints and safely remove duplicate thoughts | [@alanshurafa](https://github.com/alanshurafa) |
 | [Source Filtering](recipes/source-filtering/) | Filter thoughts by source and backfill missing metadata for early imports | [@matthallett1](https://github.com/matthallett1) |
@@ -107,7 +107,7 @@ Plain-text skill packs you can drop into Claude Code, Codex, or other AI clients
 | [Research Synthesis Skill Pack](skills/research-synthesis/) | Synthesizes source sets into findings, contradictions, confidence markers, and next questions | [@NateBJones](https://github.com/NateBJones) |
 | [Meeting Synthesis Skill Pack](skills/meeting-synthesis/) | Converts meeting notes or transcripts into decisions, action items, risks, and follow-up artifacts | [@NateBJones](https://github.com/NateBJones) |
 | [Panning for Gold Skill Pack](skills/panning-for-gold/) | Turns brain dumps and transcripts into evaluated idea inventories | [@jaredirish](https://github.com/jaredirish) |
-| [Claudeception Skill Pack](skills/claudeception/) | Extracts reusable lessons from work sessions into new skills | [@jaredirish](https://github.com/jaredirish) |
+| [Aiception Skill Pack (formerly Claudeception)](skills/claudeception/) | Extracts reusable lessons from work sessions into new skills | [@jaredirish](https://github.com/jaredirish) |
 | [Work Operating Model Skill Pack](skills/work-operating-model/) | Runs a five-layer elicitation interview and saves the approved operating model into Open Brain | [@jonathanedwards](https://github.com/jonathanedwards) |
 
 ### [`/dashboards`](dashboards/) — Frontend Templates

docs/01-getting-started.md

@@ -356,16 +356,17 @@ Follow the prompts — it may ask for your Mac password. Once it finishes, close
 
 **Without Homebrew:**
 
-```bash
-npm install -g supabase
-```
+`npm install -g supabase` is not supported. If you want a global `supabase` command, install the standalone CLI from the [official Supabase CLI guide](https://supabase.com/docs/guides/local-development/cli/getting-started). Otherwise, run every command below with `npx supabase ...`.
 
 Verify it worked:
 
 ```bash
 supabase --version
 ```
 
+> [!NOTE]
+> If you're using `npx` instead of a global `supabase` binary, run `npx supabase --version` here and prefix the rest of the commands in this section the same way.
+
 ![6.3](https://img.shields.io/badge/6.3-Log_In-555?style=for-the-badge&labelColor=1E88E5)
 
 This connects your local terminal to your Supabase account so the CLI can deploy to your project. It'll open your browser to authenticate — just follow the prompts and come back here when it says "You are now logged in."
@@ -418,10 +419,11 @@ 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:
@@ -680,7 +682,7 @@ Pick your AI client below:
 <summary>🤖 <strong>7.1 — Claude Desktop</strong></summary>
 
 > [!NOTE]
-> No JSON config files. No Node.js. No terminal. This is the simplest connection method.
+> These steps are for Anthropic's official Claude Desktop app on macOS and Windows. Linux/community ports vary and aren't officially covered by this Connectors UI flow. No JSON config files. No Node.js. No terminal. This is the simplest connection method.
 
 1. Open Claude Desktop → **Settings** → **Connectors**
 2. Click **Add custom connector**
@@ -690,27 +692,6 @@ Pick your AI client below:
 
 That's it. Start a new conversation, and Claude will have access to your Open Brain tools. You can enable or disable it per conversation via the "+" button → Connectors.
 
-> [!TIP]
-> **Prefer JSON config?** If you'd rather use `claude_desktop_config.json` instead of the Connectors UI, use `supergateway` (not `mcp-remote` — see note below):
->
-> ```json
-> {
->   "mcpServers": {
->     "open-brain": {
->       "command": "npx",
->       "args": [
->         "-y",
->         "supergateway",
->         "--streamableHttp",
->         "https://YOUR_PROJECT_REF.supabase.co/functions/v1/open-brain-mcp?key=your-access-key-from-step-5"
->       ]
->     }
->   }
-> }
-> ```
->
-> ⚠️ **Do not use `mcp-remote` for Claude Desktop.** It performs OAuth discovery against the Supabase domain, which returns a 404 that causes the connection to fail before Claude Desktop's short startup timeout. `supergateway --streamableHttp` connects directly with no OAuth handshake. (`mcp-remote` works fine in Codex because its `startup_timeout_sec = 30` gives enough time for the OAuth fallback.)
-
 </details>
 
 <details>
@@ -880,7 +861,7 @@ Your AI should retrieve the thought you just saved.
 
 **❌ Claude Desktop tools don't appear**
 
-Make sure you added the connector in Settings → Connectors (not by editing the JSON config file). Verify the connector is enabled for your conversation — click the "+" button at the bottom of the chat, then Connectors, and check that Open Brain is toggled on. If the connector was added but tools still don't show, try removing and re-adding it with the same URL.
+On the official macOS/Windows Claude Desktop app, make sure you added the connector in Settings → Connectors. Verify the connector is enabled for your conversation — click the "+" button at the bottom of the chat, then Connectors, and check that Open Brain is toggled on. If the connector was added but tools still don't show, try removing and re-adding it with the same URL. If you're using a Linux/community port, its connector behavior can differ and isn't covered by this guide.
 
 **❌ ChatGPT doesn't use the Open Brain tools**
 
@@ -890,10 +871,6 @@ First, confirm Developer Mode is enabled (Settings → Apps & Connectors → Adv
 
 Your `service_role` doesn't have table-level permissions. This happens on newer Supabase projects where CRUD grants are no longer automatic. Go back to Step 2.5 and run the `GRANT` SQL, then retry.
 
-**❌ Claude Desktop JSON config: "Couldn't reach the MCP server"**
-
-If you're using `claude_desktop_config.json` with `mcp-remote`, switch to `supergateway --streamableHttp` instead. `mcp-remote` performs OAuth discovery against the Supabase domain (`/.well-known/oauth-authorization-server`), which returns a 404 that stalls the connection past Claude Desktop's startup timeout. `supergateway` connects directly with no OAuth handshake. See Step 7.1 for the config. (This does not affect Codex, which has a configurable `startup_timeout_sec` that gives `mcp-remote` enough time to fall back.)
-
 **❌ Getting 401 errors**
 
 The access key doesn't match what's stored in Supabase secrets. Double-check that the `?key=` value in your URL matches your MCP Access Key exactly. If you're using the header approach (Claude Code or mcp-remote), the header must be `x-brain-key` (lowercase, with the dash).

docs/video-walkthrough-script.md

@@ -1,6 +1,6 @@
 # Open Brain Setup — Video Walkthrough Script
 
-**Format:** Screen recording with voiceover. Mac only. Claude Desktop demo.
+**Format:** Screen recording with voiceover. Mac only. Official Anthropic Claude Desktop app demo.
 **Tone:** Casual, confident, unhurried. You've done this before and you're showing a friend.
 **Note:** Real credentials shown on screen — delete the demo Supabase project before publishing.
 

extensions/job-hunt/README.md

@@ -132,6 +132,14 @@ Schedule a phone screen interview for my TechCorp application, tomorrow at 2pm
 Show me my pipeline overview - how many applications, what stages, upcoming interviews
 ```
 
+```
+Add a job contact at TechCorp: Jessica Lee, recruiter, jessica@techcorp.com
+```
+
+```
+Show me my TechCorp job contacts
+```
+
 ```
 Link the TechCorp recruiter to my professional CRM
 ```
@@ -146,15 +154,16 @@ A recruiter you're talking to during the job search is also a professional conta
 
 **Example workflow:**
 
-1. You add a job contact: "Jessica Lee, TechCorp recruiter, jessica@techcorp.com"
+1. You add a job contact with `add_job_contact`: "Jessica Lee, TechCorp recruiter, jessica@techcorp.com"
 2. You have multiple interactions: phone screen, interview coordination, offer negotiation
-3. Your agent uses `link_contact_to_professional_crm` to create a professional_contacts record in Extension 5
-4. The `professional_crm_contact_id` field is set, creating a bidirectional link
-5. After the job search ends, Jessica is already in your CRM with full context: company, role, all notes from the job search
+3. If you need to recover the contact later, your agent uses `search_job_contacts` to find the right `job_contact_id`
+4. Your agent uses `link_contact_to_professional_crm` to create a professional_contacts record in Extension 5
+5. The `professional_crm_contact_id` field is set, creating a bidirectional link
+6. After the job search ends, Jessica is already in your CRM with full context: company, role, all notes from the job search
 
 **How it works technically:**
 
-The tool takes a `job_contact_id` from the `job_contacts` table. It retrieves the contact details and creates a corresponding record in Extension 5's `professional_contacts` table. The `professional_crm_contact_id` field stores the link — this is application-managed rather than a database foreign key, because the two extensions live in separate table domains and you might install one without the other. This means:
+The bridge tool takes a `job_contact_id` from the `job_contacts` table. In normal use, your agent creates that row with `add_job_contact`, and if it needs to recover the UUID later it can call `search_job_contacts` first. Once it has the ID, it retrieves the contact details and creates a corresponding record in Extension 5's `professional_contacts` table. The `professional_crm_contact_id` field stores the link — this is application-managed rather than a database foreign key, because the two extensions live in separate table domains and you might install one without the other. This means:
 
 - Future interactions in the job hunt also appear in the CRM context
 - You can track the relationship long-term in Extension 5
@@ -175,12 +184,14 @@ This is the power of a fully interconnected Open Brain — context flows across
 
 1. **`add_company`** — Add a company to track (name, industry, website, size, location, remote_policy, notes, glassdoor_rating)
 2. **`add_job_posting`** — Add a specific role at a company (company_id, title, url, salary_min, salary_max, requirements, nice_to_haves, source, posted_date)
-3. **`submit_application`** — Record a submitted application (job_posting_id, status, applied_date, resume_version, cover_letter_notes, referral_contact)
-4. **`schedule_interview`** — Schedule an interview for an application (application_id, interview_type, scheduled_at, duration_minutes, interviewer_name, interviewer_title, notes)
-5. **`log_interview_notes`** — Add feedback/notes after an interview, update status to completed (interview_id, feedback, rating 1-5)
-6. **`get_pipeline_overview`** — Dashboard summary: counts by application status, upcoming interviews in next N days, recent activity. This is your "how's it going?" tool.
-7. **`get_upcoming_interviews`** — List interviews in the next N days with full company/role context
-8. **`link_contact_to_professional_crm`** — **CROSS-EXTENSION BRIDGE** — Takes a job_contact_id, creates/links to a professional_contacts record in Extension 5, sets professional_crm_contact_id
+3. **`add_job_contact`** — Add a recruiter, hiring manager, referral, or interviewer to `job_contacts` (company_id, name, title, email, phone, linkedin_url, role_in_process, notes, last_contacted)
+4. **`submit_application`** — Record a submitted application (job_posting_id, status, applied_date, resume_version, cover_letter_notes, referral_contact)
+5. **`schedule_interview`** — Schedule an interview for an application (application_id, interview_type, scheduled_at, duration_minutes, interviewer_name, interviewer_title, notes)
+6. **`log_interview_notes`** — Add feedback/notes after an interview, update status to completed (interview_id, feedback, rating 1-5)
+7. **`get_pipeline_overview`** — Dashboard summary: counts by application status, upcoming interviews in next N days, recent activity. This is your "how's it going?" tool.
+8. **`get_upcoming_interviews`** — List interviews in the next N days with full company/role context
+9. **`search_job_contacts`** — Search or list job contacts to recover recruiter/interviewer records and IDs before linking or follow-up
+10. **`link_contact_to_professional_crm`** — **CROSS-EXTENSION BRIDGE** — Takes a job_contact_id, creates/links to a professional_contacts record in Extension 5, sets professional_crm_contact_id
 
 ## Expected Outcome