fix(maproom): correct vector-search error behavior and repo-name/shared-index doc fixes (plugin-critical-fixes)

plugins/maproom/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maproom",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Semantic code search using the maproom CLI. Find code by concept, understand architecture, and explore relationships between code elements.",
   "author": {
     "name": "Daniel Bushman",

plugins/maproom/skills/maproom-search/SKILL.md

@@ -12,58 +12,38 @@ description: Semantic code search for exploring unfamiliar codebases and finding
 | Grep | Exact text/regex |
 | Glob | File paths |
 
-## First-Time Setup
+## Verifying the Shared Index
 
-### 1. Initialize Database
-```bash
-maproom db migrate
-```
-Run once per machine to create the local database.
-
-### 2. Scan Repository
-```bash
-maproom scan
-```
-Takes ~2s for small repos. Embeddings are generated by default (`--generate-embeddings true`).
-
-For large repos, run in the background:
-```bash
-nohup maproom scan > /tmp/maproom-scan.log 2>&1 &
-```
+The shared index is pre-populated and watcher-maintained — do NOT run `db migrate` or `scan`. Verify with:
 
-To regenerate embeddings separately (e.g., after model changes):
 ```bash
-maproom generate-embeddings
+export MAPROOM_DATABASE_URL=postgres://maproom:maproom@host.docker.internal:5433/maproom
+maproom status
 ```
 
-**Always run embedding generation in the background** — it makes API calls per chunk and can take minutes for large repos. Use the Bash tool's `run_in_background` parameter or `nohup`:
-```bash
-nohup maproom generate-embeddings > /tmp/maproom-embeddings.log 2>&1 &
-```
+Expected output lists all indexed repositories with their chunk counts. Use `maproom status` to discover available repo names before building search commands.
 
-### 3. Verify
-```bash
-maproom status
-```
-FTS search works immediately after scan. Vector search requires embeddings to complete.
+> **Admin operations** (`maproom db migrate`, `maproom scan`, `maproom generate-embeddings`) are owned by the watcher infrastructure and `maproom-sync`. Running them against the shared index is destructive. If you are setting up a fresh local environment, see [Appendix: Fresh-Environment Setup](#appendix-fresh-environment-setup) below.
 
 ## Choosing Search Type
 
+> **FTS-first in this environment:** All repos currently have 0% embeddings. The `search` subcommand (FTS) is the operative path. The `vector-search` subcommand will exit with code 2 and an embedding provider error until embeddings are generated. Use FTS for all searches now.
+
 | You Have | Use | Example |
 |----------|-----|---------|
-| Exact function/variable name | `search` | `--query "validate_state_file_schema"` |
-| Known terminology | `search` | `--query "autogate ready block"` |
-| Conceptual question | `vector-search` | `--query "how to pause automated work"` |
-| Exploring unfamiliar code | `vector-search` | `--query "authentication flow"` |
-| Finding code patterns | `search` | `--query "try except json"` |
+| Exact function/variable name | `search` (FTS) | `--query "validate_state_file_schema"` |
+| Known terminology | `search` (FTS) | `--query "autogate ready block"` |
+| Finding code patterns | `search` (FTS) | `--query "try except json"` |
+| Conceptual question | `search` (FTS) now; `vector-search` when embeddings available | `--query "how to pause automated work"` |
+| Exploring unfamiliar code | `search` (FTS) now; `vector-search` when embeddings available | `--query "authentication flow"` |
 
-**Rule of thumb:** Know the words? Use `search`. Know the concept? Use `vector-search`.
+**Rule of thumb:** Know the words? Use `search`. Know the concept? Use `vector-search` (only when embeddings are present).
 
 ### Vector Search Syntax
 ```bash
 maproom vector-search --repo <repo> --query "<query>" --format agent
 ```
-Requires embeddings (see First-Time Setup step 2).
+Requires embeddings. Check `maproom status` — if `Embeddings: 0 (0.0%)`, vector-search will exit with code 2 (`embedding_provider` error: no Google credentials found). Use the `search` subcommand (FTS) instead.
 
 ### Evidence from Testing
 
@@ -280,7 +260,7 @@ maproom vector-search --repo specs --query "authentication design decisions" --f
 ```
 2. Then check the code repo for implementation:
 ```bash
-maproom vector-search --repo code --query "authentication login flow" --format agent
+maproom vector-search --repo manifoldlogic/crewchief --query "authentication login flow" --format agent
 ```
 3. Expand context on a relevant code result:
 ```bash
@@ -297,17 +277,52 @@ For detailed error recovery steps, see [troubleshooting.md](./references/trouble
 **Token limit exceeded** (`input token count is ... but the model supports up to 20000`):
 Re-run with smaller batches: `maproom generate-embeddings --batch-size 25`
 
-**Vector search returns no results** (search completes but returns empty):
-Verify embeddings exist: `maproom status` — if missing, run `maproom generate-embeddings`
+**Vector search fails with embedding provider error** (exits with code 2, `embedding_provider` error):
+All repos currently have 0% embeddings — vector-search exits with an error, it does NOT complete with empty results. Use the `search` subcommand (FTS) instead. Vector search requires Google credentials and embeddings to be generated first.
 
 **No repositories indexed** (status shows no repositories):
-Run First-Time Setup above to scan and index your repository.
+The shared index should already be populated. Verify `MAPROOM_DATABASE_URL` is set to the Postgres URL: `postgres://maproom:maproom@host.docker.internal:5433/maproom`. If you are setting up a fresh local environment, see [Appendix: Fresh-Environment Setup](#appendix-fresh-environment-setup).
 
 **Stale results after code changes** (results reference old or deleted code):
-Re-scan the repository: `maproom scan`
+The watcher infrastructure re-indexes automatically. If results are persistently stale, contact the index admin.
 
 **Irrelevant results** (results don't match intent):
 Check Choosing Search Type above — FTS for exact terms, vector for concepts. Use 2-3 core terms.
 
 ## Query Tips
 Extract 2-3 terms from questions. See [search-best-practices.md](./references/search-best-practices.md).
+
+---
+
+## Appendix: Fresh-Environment Setup
+
+> **This appendix is for admin/owner use only.** Do NOT run these commands against the shared index. The shared Postgres index is maintained by watchers and `maproom-sync`.
+
+If you are setting up a brand-new local environment (not the shared devcontainer), use these steps:
+
+### 1. Initialize Database
+```bash
+maproom db migrate
+```
+Run once per machine to create the local database schema.
+
+### 2. Scan Repository
+```bash
+maproom scan --path <repo-path> --repo <owner/repo>
+```
+Takes ~2s for small repos. For large repos, run in the background:
+```bash
+nohup maproom scan --path <repo-path> --repo <owner/repo> > /tmp/maproom-scan.log 2>&1 &
+```
+
+### 3. Generate Embeddings (Optional)
+Required only for `vector-search`. Always run in the background:
+```bash
+nohup maproom generate-embeddings --repo <owner/repo> > /tmp/maproom-embeddings.log 2>&1 &
+```
+
+### 4. Verify
+```bash
+maproom status
+```
+FTS search works immediately after scan. Vector search requires embeddings to complete.