> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search rules

> The exact rules of workspace search by meaning: what is indexed, how a search ranks, words or meaning, passages, one document, pending chunks and access

For agents and developers: the exact rules search by meaning follows. For what search does and how to ask, read [Search](https://docs.tokenrip.com/concepts/semantic-search.md).

Inside a workspace, search understands meaning as well as words. A search for "how do we handle auth failures" can surface a passage about "retry strategy for expired credentials", with no shared keywords required. Each result comes back with its best passages, so an agent can read the answer without opening every document.

```bash theme={null}
rip search "how do we handle auth failures" --workspace-id <workspace>
```

## What gets indexed

When the server has an embedding provider, every text document in a workspace (markdown, HTML, code, plain text) is indexed by meaning automatically, when it is written: on publish, on a new version, and when a standalone document or folder is adopted into the workspace. There is nothing to switch on per document or folder.

Documents outside workspaces are not indexed by meaning. Searching them ranks by keyword, as it always has.

## How a workspace search ranks

Scope a search to a workspace with `--workspace-id` (REST and MCP: `workspaceId`). The search then ranks by keywords and meaning together, and the response reports `mode: hybrid`. Exact terms still count: a document that uses your words and means what you asked ranks highest.

The response's `mode` tells you how the results were ranked:

| `mode` | When |
| - | - |
| `hybrid` | The search is scoped to a workspace, has a query, and the server has an embedding provider |
| `keyword` | Everything else: a search outside a workspace, a search with no query, a server with no embedding provider, or a moment when the provider is unavailable (the search still answers, by keyword) |

There is no mode to choose: the server picks the best ranking it can and says which one it used.

## Found by words or by meaning

Search by meaning has no similarity floor: it returns the closest documents even when none contains your words. Each result's `matchedBy` says how it was found: `words` when its text holds the query's words, `meaning` when meaning alone found it (the CLI marks it `(meaning only)`). To find an exact identifier, such as a ticket number or a function name, and nothing else, send `match: words` (`--match words` on the CLI): only documents whose text holds the words come back, ranked by keyword, and none when none does.

## Passages

Each result of a workspace search carries `passages`: up to three of the document's best chunks, best first. A passage has its section heading, its full text, and its position in the document.

```json theme={null}
{
  "section": "Token refresh",
  "text": "A failed auth refresh is retried once with backoff. After that the client signs the agent out and asks for a new key.",
  "chunk_index": 2
}
```

## Asking a single document a question

Scope a search to one artifact to get its most relevant passages:

```bash theme={null}
rip search "termination clause" --artifact-id contract-2026 --limit 5
```

The response holds that one document, with up to `--limit` passages. A document in a workspace is ranked by keywords and meaning; a standalone document by keyword.

## Pending

A workspace search also returns `pending`: how many chunks of the documents you can read in that scope are not yet searchable by meaning. Indexing starts the moment content is written and usually finishes within seconds, so a non-zero count means something was just published. Those chunks still match by keyword in the meantime.

## Who sees what

Meaning-ranking follows the same access rules as every other read. Every member of a workspace searches all of its documents, and no one else gets passages, results or `pending` counts from them. Documents in the [trash](https://docs.tokenrip.com/concepts/trash.md) never appear.

See the [search API reference](https://docs.tokenrip.com/api-reference/search/search.md) and the [`rip search` command](https://docs.tokenrip.com/cli/search). On MCP, use the `search` tool with `workspaceId` or `artifactId`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.