docs(maproom): replace INTERIM cross-repo guidance with native 0.3.0 flags (plugin 0.10.3)

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

@@ -1,6 +1,6 @@
 {
   "name": "maproom",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "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/agents/maproom-researcher.md

@@ -47,30 +47,33 @@ maproom status
 
 Then select the most relevant repo for the research question.
 
-<!-- INTERIM: replaced when cross-repo search ships (see maproom-eco-rust-cross-repo-search) -->
 ### Multi-repo tasks
 
-When a task spans multiple repositories, enumerate available repos first, then search each one individually:
+Maproom 0.3.0 supports native cross-repo search — use `--all-repos` or repeatable `--repo` flags instead of a per-repo loop.
 
+**Sweep all indexed repos in one call:**
 ```bash
-# Step 1: list all indexed repos (shared-Postgres environments return the full inventory)
-maproom status --json
+QUERY="<search terms>"
+maproom search --all-repos --query "$QUERY" --k 10 --format agent
 ```
 
-Parse the `repos[].name` values from the JSON output to build your repo list. Then issue a separate search per repo:
+`--k` is a **per-repo cap**: with `--all-repos` and `--k 10`, you receive up to 10 results per repo, grouped by repo. Results use `repo:file:line` format in `--format agent` output so the source repo is always visible.
 
+**Target specific repos only:**
 ```bash
-# Step 2: search each repo in turn
 QUERY="<search terms>"
-maproom search --repo <repo-name> --query "$QUERY" --k 10 --format agent
+maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k 10 --format agent
 ```
 
-A local convenience wrapper (`maproom-all`) may be present in some environments; use it if available, but do not assume it exists — the per-repo loop above is portable.
+`--repo` is repeatable. Use it when you know which repos are relevant and want to avoid sweeping the full index.
+
+**Scope rules:**
+- `--all-repos` and `--repo` are mutually exclusive — pass one or the other. `--repo` is repeatable; single and multiple uses are the same flag, not different scope types.
+- The `vector-search` subcommand and `search --mode hybrid` / `search --mode vector` do **not** support multi-repo scope; they exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use `search` (FTS / default mode) for cross-repo sweeps.
 
-**`--repo specs` is available in shared-Postgres environments** and covers indexed specification documents. Include it explicitly when the task involves specs.
+**Search budget:** One `--all-repos` call counts as **one search** against your session cap (soft=5, hard=10). Prefer a single `--all-repos` call over N single-repo calls — it is equivalent in cost but substantially faster.
 
-**No server-side cross-repo search yet.** There is no `--all-repos` flag. Each search targets exactly one repo. Cross-repo synthesis is done by the agent after collecting results from each repo in sequence.
-<!-- end INTERIM -->
+**`--repo specs`** covers indexed specification documents in shared-Postgres environments. It is a valid target for both single-repo and multi-repo invocations.
 
 ## Critical Rules
 <!-- MAPCAP: soft=5, hard=10 - DO NOT UPDATE without checking all 5 prompt sections -->
@@ -105,7 +108,7 @@ maproom search --repo <repo> --query <search terms> --format agent
 
 Before beginning the 4-phase workflow:
 
-1. **CLI Version Check:** Run `maproom --version` and verify version 0.2.0 or higher. If version check fails, report error and halt execution.
+1. **CLI Version Check:** Run `maproom --version` and verify version 0.3.0 or higher. If version check fails, report error and halt execution.
 2. **Query Validation:** Reject null, empty, or whitespace-only queries. Valid query pattern: at least one non-whitespace character.
 
 ## Query Classification (Before Phase 1)
@@ -347,4 +350,4 @@ Instead:
 **Security:** Do not include actual credentials, access tokens, or project IDs in your findings output. Use placeholders like `YOUR_PROJECT_ID`.
 
 ### CLI and Query Validation
-See Pre-Workflow Checks section above. Version 0.2.0 or higher required; null/empty queries rejected.
+See Pre-Workflow Checks section above. Version 0.3.0 or higher required; null/empty queries rejected.

plugins/maproom/scripts/verify-docs.sh

@@ -39,6 +39,10 @@ CHECKS:
   9.  New flags (--kind/--lang/--preview/--preview-length/--threshold) in SKILL.md (>= 5)
   10. --format agent in troubleshooting.md (informational)
   11. Cross-reference integrity (./references/*.md and ./templates/* links in SKILL.md)
+  12. No INTERIM markers in plugins/maproom/ (zero hits)
+  13. 0.3.0 version floor in maproom-researcher.md (>= 1)
+  14. --all-repos flag documented in maproom-researcher.md (>= 1)
+  15. Search-budget note (--all-repos = one search) in maproom-researcher.md (>= 1)
 
 EXIT CODES:
   0   All checks passed
@@ -97,7 +101,7 @@ fi
 # ---------------------------------------------------------------------------
 PASS_COUNT=0
 FAIL_COUNT=0
-TOTAL_CHECKS=11
+TOTAL_CHECKS=15
 
 # ---------------------------------------------------------------------------
 # JSON accumulation
@@ -404,6 +408,59 @@ else
   json_add_result 11 "Cross-reference integrity" "fail" "$broken" 0 "$broken of $total_refs cross-references are broken"
 fi
 
+# ===========================================================================
+# Check 12: No INTERIM markers in plugins/maproom/ (zero hits)
+# ===========================================================================
+AGENT_MD="$PLUGIN_DIR/agents/maproom-researcher.md"
+human_echo "Check 12: No INTERIM markers in plugins/maproom/"
+interim_count=$(grep -rn "INTERIM" "$PLUGIN_DIR" | grep -v "verify-docs.sh" | grep -c "INTERIM" || true)
+if [ "$interim_count" -eq 0 ]; then
+  report_pass "No INTERIM markers found"
+  json_add_result 12 "No INTERIM markers in plugins/maproom/" "pass" 0 0 "No INTERIM markers found"
+else
+  report_fail "$interim_count INTERIM marker(s) found — remove before shipping"
+  json_add_result 12 "No INTERIM markers in plugins/maproom/" "fail" "$interim_count" 0 "$interim_count INTERIM marker(s) found"
+fi
+
+# ===========================================================================
+# Check 13: 0.3.0 version floor in maproom-researcher.md (>= 1)
+# ===========================================================================
+human_echo "Check 13: 0.3.0 version floor in maproom-researcher.md"
+count=$(grep -c "0\.3\.0" "$AGENT_MD" || true)
+if [ "$count" -ge 1 ]; then
+  report_pass "$count occurrences (>= 1 required)"
+  json_add_result 13 "0.3.0 version floor in maproom-researcher.md" "pass" "$count" 1 "$count occurrences (>= 1 required)"
+else
+  report_fail "$count occurrences (>= 1 required)"
+  json_add_result 13 "0.3.0 version floor in maproom-researcher.md" "fail" "$count" 1 "$count occurrences (>= 1 required)"
+fi
+
+# ===========================================================================
+# Check 14: --all-repos documented in maproom-researcher.md (>= 1)
+# ===========================================================================
+human_echo "Check 14: --all-repos flag documented in maproom-researcher.md"
+count=$(grep -c "\-\-all-repos" "$AGENT_MD" || true)
+if [ "$count" -ge 1 ]; then
+  report_pass "$count occurrences (>= 1 required)"
+  json_add_result 14 "--all-repos documented in maproom-researcher.md" "pass" "$count" 1 "$count occurrences (>= 1 required)"
+else
+  report_fail "$count occurrences (>= 1 required)"
+  json_add_result 14 "--all-repos documented in maproom-researcher.md" "fail" "$count" 1 "$count occurrences (>= 1 required)"
+fi
+
+# ===========================================================================
+# Check 15: Search-budget note in maproom-researcher.md (>= 1)
+# ===========================================================================
+human_echo "Check 15: Search-budget note (--all-repos = one search) in maproom-researcher.md"
+count=$(grep -c "one search\|one.*--all-repos\|--all-repos.*one" "$AGENT_MD" || true)
+if [ "$count" -ge 1 ]; then
+  report_pass "$count occurrences (>= 1 required)"
+  json_add_result 15 "Search-budget note in maproom-researcher.md" "pass" "$count" 1 "$count occurrences (>= 1 required)"
+else
+  report_fail "$count occurrences (>= 1 required)"
+  json_add_result 15 "Search-budget note in maproom-researcher.md" "fail" "$count" 1 "$count occurrences (>= 1 required)"
+fi
+
 # ===========================================================================
 # Output
 # ===========================================================================

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

@@ -250,7 +250,20 @@ This lists all repos that have been scanned and are available for search.
 
 ### Cross-Repo Search Workflow
 
-When a question spans both design and implementation, search across repos sequentially.
+**Native multi-repo search (maproom 0.3.0+):** Use `--all-repos` or repeatable `--repo` flags to query multiple repos in a single call. One invocation counts as **one search** against your session cap.
+
+```bash
+# Sweep all indexed repos
+QUERY="authentication middleware"
+maproom search --all-repos --query "$QUERY" --k 10 --format agent
+
+# Target specific repos only
+maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k 10 --format agent
+```
+
+Note: `vector-search` does not support multi-repo scope — use FTS (`search`) for cross-repo sweeps.
+
+**Sequential search (specs → code):** When a question spans design rationale and implementation, search specs for *why*, then code for *how*.
 
 **Example: Understanding why and how authentication works**
 

plugins/maproom/skills/maproom-search/references/multi-repo-guide.md

@@ -162,6 +162,50 @@ maproom search --repo specs --query "decision rationale" --format agent
 
 Results from docs repos include `heading_1`, `heading_2`, `heading_3`, and `heading_4` chunks that reveal the document hierarchy. Use the `file_relpath` and line numbers to navigate to specific sections.
 
+## Native Cross-Repo Search (maproom 0.3.0+)
+
+Maproom 0.3.0 adds server-side cross-repo search — a single CLI invocation queries multiple repos in one round-trip, returning results grouped by repo with `repo:file:line` coordinates.
+
+### `--all-repos`: sweep the full index
+
+```bash
+QUERY="authentication middleware"
+maproom search --all-repos --query "$QUERY" --k 10 --format agent
+```
+
+`--k` is a **per-repo cap**: `--k 10` returns up to 10 hits per repo. Results are grouped by repo so you can see which repos contain relevant code at a glance.
+
+**Search budget:** One `--all-repos` call counts as **one search** against the session cap (soft=5, hard=10). Prefer it over N single-repo calls — it is equivalent in cost but substantially faster.
+
+### `--repo` (repeatable): target specific repos
+
+```bash
+QUERY="embedding pipeline"
+maproom search --repo manifoldlogic/crewchief --repo specs --query "$QUERY" --k 10 --format agent
+```
+
+Pass `--repo` more than once to search a named subset of repos in a single call. Use this when you know which repos are relevant.
+
+### Scope rules
+
+- `--all-repos` and `--repo` are mutually exclusive — pass one or the other. `--repo` is repeatable; single and multiple uses are the same flag, not different scope types.
+- The `vector-search` subcommand and `search --mode hybrid` / `search --mode vector` do **not** support multi-repo scope. They exit with code 2 if `--all-repos` or multiple `--repo` flags are passed. Use `search` (FTS / default mode) for cross-repo sweeps.
+- `--repo specs` covers indexed specification documents in shared-Postgres environments and is a valid target for both single-repo and multi-repo calls.
+
+### Pre-0.3.0 fallback
+
+If you are on an environment running maproom older than 0.3.0, native cross-repo flags are unavailable. Fall back to the per-repo loop:
+
+```bash
+# Pre-0.3.0 fallback only — superseded by --all-repos / repeatable --repo in 0.3.0
+QUERY="authentication middleware"
+for repo in manifoldlogic/crewchief manifoldlogic/claude-code-plugins specs; do
+  maproom search --repo "$repo" --query "$QUERY" --k 10 --format agent
+done
+```
+
+A local convenience wrapper (`maproom-all`) performs the same loop in some environments. Both approaches are superseded by native flags once 0.3.0 is installed.
+
 ## Cross-Repo Patterns
 
 These patterns combine searches across code and docs repos to answer questions that neither repo can answer alone. Each pattern starts in one repo type and follows up in the other.