# Workspace RAG

> Index workspace documents into the Soapbox RAG system and search across them semantically. Use when the user wants to search their project documents, asks "what do my files say about X", needs to find information across multiple PDFs or spreadsheets, or wants to make documents searchable for downstream skills. Also use proactively after workspace-setup to index the project folder. Triggers on: "index my documents", "search my files", "what does the PCNA say about X", "find mentions of X across documents", "ingest files into search".

- Skill: `soapboxbuild/workspace-rag` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add soapboxbuild/workspace-rag`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soapboxbuild/workspace-rag/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: soapboxbuild (https://skillmd.com/u/soapboxbuild)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/soapboxbuild/workspace-rag

---


# Workspace RAG

Index project documents into the Soapbox RAG system and run semantic searches
across them. The RAG index persists across sessions and is shared with all agents
in the org.

**Required:** Soapbox RAG (provides `rag_ingest`, `rag_search`, `rag_list`, `rag_delete`)  
**Optional:** `.audette-config.json` (for workspace scoping)

---

## When to Use RAG vs. Direct File Reading

| Use RAG when | Use Read tool when |
|---|---|
| Searching across many files | Reading one known file |
| Query is semantic ("what type of HVAC...") | Query is exact ("show me line 45 of...") |
| File contents are already indexed | File was just added and not yet indexed |
| Cross-document synthesis needed | Single-document extraction |

---

## Step 1: Check What's Already Indexed

Call `rag_list` with the workspace_id from `.audette-config.json` (if available):

```
rag_list(workspace_id: "ws_abc123")
```

If the document you need is already indexed and recent, skip to Step 3.
If the project has never been indexed, proceed to Step 2.

---

## Step 2: Ingest Documents

Call `rag_ingest` for each relevant file. Supported types: PDF, XLSX, DOCX, TXT, MD, CSV.

```
rag_ingest(
  file_path: "/absolute/path/to/document.pdf",
  workspace_id: "ws_abc123",   // from .audette-config.json, or omit for org-wide
  source: "agent"
)
```

**Returns:** `{ documentId, chunkCount, skipped }` — `skipped: true` means the file was already indexed with the same content (idempotent).

**Batch indexing:** To index an entire project folder, list the files first and call `rag_ingest` for each supported file. Skip images and binary files.

**workspace_id:** Always pass the workspace_id from `.audette-config.json` to scope documents to the current project. Omit only for org-wide reference documents.

---

## Step 3: Search

Call `rag_search` with a natural language query:

```
rag_search(
  query: "what type of heating system does the building have",
  workspace_id: "ws_abc123",
  limit: 5
)
```

**Returns:** `{ results: [{ content, filename, workspaceId, score }] }`

Search finds semantically relevant chunks — it doesn't need exact keyword matches. Good queries:
- "HVAC system type and installation year"
- "boiler capacity MBH"
- "year built construction type"
- "utility account number electricity"

**Workspace scope:** Searches the specified workspace AND org-wide documents together. Workspace results are weighted higher.

---

## Step 4: Use the Results

Results come as text chunks with source filenames and relevance scores. For each result:
- Note the `filename` to understand the source
- The `content` is a 512-token excerpt — enough context for most extractions
- Higher `score` = more relevant

If results are insufficient, try:
- A different query phrasing
- Ingesting additional documents (Step 2)
- Increasing `limit` (max 20)

---

## Step 5: Keep the Index Fresh

After adding new documents to the workspace:
- Call `rag_ingest` for each new file — already-indexed files are skipped automatically
- No need to delete and re-index unless a file's content changed

To remove a document:
```
rag_delete(document_id: "uuid-of-document")
```

---

## Integration with Other Skills

**workspace-setup** calls this skill automatically after initialization to index the project folder.

**audette-energy-data** can search RAG for utility bill data instead of reading files directly, when documents are already indexed.

**audette-equipment-survey** uses RAG to find equipment details in PCNAs and CNAs.

**system-details** calls `rag_search` to pull context from documents before synthesizing a building systems report.

---

## Rules

- Always use the `workspace_id` from `.audette-config.json` — never mix org-wide and workspace-scoped indexes
- Ingest before searching if the workspace has never been indexed
- `rag_ingest` is idempotent — safe to call repeatedly on the same file
- Don't ingest image files, videos, or binaries — they produce no text
- For sensitive documents, confirm with the user before indexing