docs(search): relocate /search setup to docs and fix dead URLs (#170)

Signed-off-by: Logan Nguyen <lg.131.dev@gmail.com>

Author: quiet-node

README.md

@@ -138,30 +138,7 @@ bun run sandbox:stop
 
 For the full architecture and security philosophy behind the sandbox, see [`sandbox/README.md`](sandbox/README.md).
 
-### Step 2: Setup the search sandbox (Optional, required for /search)
-
-The `/search` command uses an agentic search pipeline that depends on two local Docker containers: a **SearXNG** meta-search engine and a **Trafilatura** reader. This setup ensures that your search queries and the content you read remain entirely local.
-
-**Prerequisite:** [Docker Desktop](https://www.docker.com/get-started) must be running.
-
-1. **Start the search services**
-
-   ```bash
-   bun run search-box:start
-   ```
-
-2. **Verify services (Optional)**
-
-   ```bash
-   # Search Engine check:
-   curl "http://127.0.0.1:25017/search?q=thuki&format=json"
-   ```
-
-   Without this service running, the `/search` command will be disabled in the chat, but all other features will remain available.
-
-   For more details on the agentic search pipeline, see [docs/agentic-search.md](docs/agentic-search.md).
-
-### Step 3: Install Thuki
+### Step 2: Install Thuki
 
 #### Download (Recommended)
 
@@ -197,6 +174,12 @@ bun run dev
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development setup guide.
 
+### Optional: Enable `/search`
+
+The `/search` command runs a fully local agentic search pipeline backed by two Docker services (SearXNG + a Trafilatura reader). It is **not bundled with the `.dmg`**: enabling it currently requires cloning this repository to run the local services. Every other Thuki feature works without it. First-class, out-of-box `/search` support is on the roadmap.
+
+See [docs/agentic-search.md#setup](docs/agentic-search.md#setup) for the setup steps.
+
 ## Architecture & Security
 
 <details>

docs/agentic-search.md

@@ -4,6 +4,43 @@ A deep dive into Thuki's agentic RAG search pipeline: how retrieval-augmented ge
 
 ---
 
+## Setup
+
+> **Roadmap:** First-class, out-of-box `/search` support (bundled native sidecars or pre-built container images shipped with the app) is planned. Today, enabling `/search` requires cloning this repository to run the local Docker services described below. Track progress and contribute in the project's [GitHub issues](https://github.com/quiet-node/thuki/issues).
+
+The `/search` command depends on two local Docker containers: a **SearXNG** meta-search engine and a **Trafilatura** reader. Both run on `127.0.0.1` only, so every query and every fetched page stays on your machine.
+
+**Prerequisites**
+
+- [Docker Desktop](https://www.docker.com/get-started) installed and running.
+- [Bun](https://bun.sh) installed (used to launch the Compose stack).
+- A local clone of the Thuki repository.
+
+**Start the services**
+
+```bash
+git clone https://github.com/quiet-node/thuki.git
+cd thuki
+bun install
+bun run search-box:start
+```
+
+**Verify (optional)**
+
+```bash
+curl "http://127.0.0.1:25017/search?q=thuki&format=json"
+```
+
+**Stop the services**
+
+```bash
+bun run search-box:stop
+```
+
+Without these services running, the `/search` command stays disabled in the chat; every other Thuki feature continues to work normally.
+
+---
+
 ## The Problem
 
 To understand why `/search` is built the way it is, it helps to understand what simpler approaches get wrong. There are three of them.

docs/commands.md

@@ -30,7 +30,7 @@ Runs agentic web search and answers from live sources with citations.
 
 **Behavior:** Routes the message through Thuki's local search pipeline instead of plain chat. Answers are grounded in retrieved web sources and typically include inline citations plus a Sources footer.
 
-**Limit:** Requires the search sandbox to be running. Use it for current, changing, or cutoff-sensitive information.
+**Limit:** Requires the search sandbox to be running. See [agentic-search.md#setup](agentic-search.md#setup) for setup steps. Use it for current, changing, or cutoff-sensitive information.
 
 ---
 

src-tauri/src/search/types.rs

@@ -437,8 +437,8 @@ impl SearchError {
             Self::SandboxUnavailable => {
                 "Thuki's search sandbox isn't running.\n\
                 The /search command needs two local containers (SearXNG and a Trafilatura reader) to be up. \
-                See the setup steps in the repo README:\n\
-                https://github.com/quiet-node/thuki/blob/main/README.md#setup-the-search-sandbox-optional-required-for-search"
+                See the setup guide:\n\
+                https://github.com/quiet-node/thuki/blob/main/docs/agentic-search.md#setup"
                     .to_string()
             }
         }

src/components/SandboxSetupCard.tsx

@@ -8,7 +8,7 @@ import { invoke } from '@tauri-apps/api/core';
  */
 export function SandboxSetupCard() {
   const SETUP_URL =
-    'https://github.com/quiet-node/thuki#step-2-setup-the-search-sandbox-optional-required-for-search';
+    'https://github.com/quiet-node/thuki/blob/main/docs/agentic-search.md#setup';
 
   const handleOpenGuide = () => {
     void invoke('open_url', { url: SETUP_URL });

src/components/__tests__/SandboxSetupCard.test.tsx

@@ -35,7 +35,7 @@ describe('SandboxSetupCard', () => {
     const button = screen.getByRole('button', { name: /Setup Guide/i });
     fireEvent.click(button);
     expect(invoke).toHaveBeenCalledWith('open_url', {
-      url: 'https://github.com/quiet-node/thuki#step-2-setup-the-search-sandbox-optional-required-for-search',
+      url: 'https://github.com/quiet-node/thuki/blob/main/docs/agentic-search.md#setup',
     });
   });
 

src/config/commands.ts

@@ -69,7 +69,7 @@ export const COMMANDS: readonly Command[] = [
       behavior:
         "Routes the message through Thuki's local search pipeline instead of plain chat. Answers are grounded in retrieved web sources and typically include inline citations plus a Sources footer.",
       limit:
-        'Requires the search sandbox to be running. Use it for current, changing, or cutoff-sensitive information.',
+        'Requires the search sandbox to be running. See [agentic-search.md#setup](agentic-search.md#setup) for setup steps. Use it for current, changing, or cutoff-sensitive information.',
     },
     promptHelp: {
       summary: 'agentic web search for current or cutoff-sensitive questions.',