Narrowing what retrieval can return

The short answer

In paqad-ai 1.91.1 you control what retrieval can return mainly by controlling what goes into the index, through the file .paqad/rag.ignore.yaml. Retrieval (RAG, short for retrieval-augmented generation) is Paqad's optional project search, explained in the RAG overview. On top of the index, Paqad applies a fixed scope rule when it delivers passages. There is no per-workflow or per-step filter setting.

Three places where results are narrowed

1. The index filter decides which files are indexed at all. You can adjust it.
2. The delivery scope decides which indexed passages the background refresh hands to the AI. It is fixed in 1.91.1.
3. A metadata filter component inside the package can narrow passages by file type, module path, framework or age. It is used only by a library-level loader that no command or hook calls in 1.91.1.

Adjusting the index with rag.ignore.yaml

Paqad works out which files to index with four script checks (file type, hard exclusions, ignore rules, and file checks such as size and binary content). The RAG overview lists them. Create .paqad/rag.ignore.yaml to change the defaults:

version: 1
exclude:
  - "docs/archive/**"
include:
  - "legacy/important/**"
additional_extensions:
  - ".sql"
additional_basename_includes:
  - "Taskfile"
additional_named_file_exclusions:
  - "generated-schema.json"
use_project_ignore_files: true
use_global_gitignore: false

Key	What it does
version	Required. Must be 1.
exclude	Extra path patterns to leave out of the index.
include	Path patterns to keep even if an ignore rule, a default excluded folder, a stack pack exclusion, an exclude entry or the .env rule would drop them.
additional_extensions	More file extensions to treat as indexable.
additional_basename_includes	More file names to index, such as build files without an extension.
additional_named_file_exclusions	Exact file names to always leave out.
use_project_ignore_files	Respect .gitignore files and .ignore, .fdignore and .rgignore at the project root. Default true.
use_global_gitignore	Also respect your personal global gitignore. Default false.

Some exclusions cannot be overridden by include: anything under .paqad/, AI tool folders, lockfiles, generated AI entry files, and files that fail the type, size, binary or encoding checks. If the file does not match the expected format, Paqad logs a warning and uses the defaults. Run paqad-ai rag rebuild after a change so the index reflects it.

The delivery scope

The code can deliver documentation only, code only, or both. It is designed to give code-changing workflows both documentation and code passages. In 1.91.1, however, the background refresh does not pass the workflow to this step, so it always uses the documentation-only scope: passages from docs/instructions/, docs/modules/ and the module map file. Source code can be in the index without being injected on this path.

The metadata filter component

The package includes a filter that narrows passages by four kinds of metadata: file extension, module path prefix, framework, and how recently the file changed. The filters are combined, so a passage must pass all of them. If fewer than three passages would survive, the filter is dropped and the full set is used, so filtering never leaves the AI with almost nothing. The filter values are filled in automatically from signals about the task, not written by you.

Checking what is indexed and returned

• paqad-ai rag status shows the index state.
• paqad-ai rag probe "your query" lists the top matching files and scores before the confidence floor, which shows whether a file you expected is being found.