mothership agent-cli: grep --in <world> narrows the scope; docs-search fallback names CLI commands

- universal grep: --in with a world name (tables, blocks, …) searches that
  world instead of filtering resources by a name that never matches; the
  no-match line lists only the worlds actually searched.
- docs search: the shortfall notes point at blocks get / blocks tips instead
  of a glob() the agent surface does not have.

Claude-Session: https://claude.ai/code/session_01HFVhPDtRZuCgupPco633w8

Author: Sg312

apps/sim/lib/mothership/agent-cli/engines/universal-grep.ts

@@ -241,14 +241,19 @@ export const universalGrepCommand: AgentCliEngine = {
     const ignoreCase = flags.i === true
     const countOnly = flags.count === true
     const within = typeof flags.in === 'string' ? flags.in.toLowerCase() : undefined
+    // `--in tables` reads as "search the tables world", so a world name narrows the scope;
+    // anything else is a resource id or name inside the searched worlds.
+    const withinScope = SCOPES.find((scope) => scope === within)
+    const searched: Scope[] = withinScope ? [withinScope] : scopes
+    const nameFilter = withinScope ? undefined : within
     const matches = compilePattern(pattern, ignoreCase)
 
     const materialized = (
-      await Promise.all(scopes.map((scope) => MATERIALIZERS[scope](runtime)))
+      await Promise.all(searched.map((scope) => MATERIALIZERS[scope](runtime)))
     ).flat()
-    const candidates = within
+    const candidates = nameFilter
       ? materialized.filter(
-          (m) => m.id.toLowerCase() === within || m.label.toLowerCase().includes(within)
+          (m) => m.id.toLowerCase() === nameFilter || m.label.toLowerCase().includes(nameFilter)
         )
       : materialized
 
@@ -282,7 +287,7 @@ export const universalGrepCommand: AgentCliEngine = {
     }
     if (out.length === 0) {
       return agentCliOk(
-        `No matches for ${JSON.stringify(pattern)} in ${scopes.join(', ')}${within ? ` within "${within}"` : ''}.`
+        `No matches for ${JSON.stringify(pattern)} in ${searched.join(', ')}${nameFilter ? ` within "${nameFilter}"` : ''}.`
       )
     }
     const truncated =

apps/sim/lib/mothership/tools/server/docs/search-docs.test.ts

@@ -80,8 +80,7 @@ describe('searchDocsServerTool', () => {
     const output = await searchDocsServerTool.execute({ query: 'brand new feature' }, CONTEXT)
 
     expect(output.note).toContain('search index may lag')
-    expect(output.note).toContain('read it directly')
-    expect(output.note).toContain('glob("docs/**")')
+    expect(output.note).toContain('blocks tips')
   })
 
   it('explains an empty result set caused by filtering, so it does not read as missing docs', async () => {

apps/sim/lib/mothership/tools/server/docs/search-docs.ts

@@ -31,7 +31,7 @@ interface SearchDocsOutput {
 function shortfallNote(outcome: Awaited<ReturnType<typeof searchDocs>>): string | undefined {
   const { results, candidatesConsidered, droppedBelowThreshold, droppedStale } = outcome
   if (results.length === 0 && candidatesConsidered === 0) {
-    return 'No indexed candidates were returned. The search index may lag the live docs. If you know the page, read it directly; otherwise use glob("docs/**") to find the current path.'
+    return 'No indexed candidates were returned. The search index may lag the live docs. Rephrase the query, or read the block definition and tips directly (blocks get / blocks tips).'
   }
   if (droppedBelowThreshold === 0 && droppedStale === 0) return undefined
 
@@ -46,7 +46,7 @@ function shortfallNote(outcome: Awaited<ReturnType<typeof searchDocs>>): string
   const dropped = reasons.join(' and ')
 
   return results.length === 0
-    ? `No relevant matches. The search index returned ${candidatesConsidered} candidate(s), but ${dropped} — this does NOT mean the docs lack this topic. Rephrase the query, widen it by dropping the path scope, or browse with glob("docs/**").`
+    ? `No relevant matches. The search index returned ${candidatesConsidered} candidate(s), but ${dropped} — this does NOT mean the docs lack this topic. Rephrase the query, widen it by dropping the path scope, or read the block definition and tips directly (blocks get / blocks tips).`
     : `Returned ${results.length} of ${candidatesConsidered} candidate(s); ${dropped}. Rephrase or widen the query if these look off-topic.`
 }