---
name: math-reference
description: Look up mathematical definitions, theorems, proofs, and worked examples by consulting the user's curated PDF library at ~/Documents/3 Resources/Maths before falling back to web search. Use whenever a task needs an authoritative math reference — definitions, statements of theorems, proofs, classical results, textbook examples — across pure or applied mathematics. Prefer this over reciting from memory or going straight to the web.
---

# Math Reference

Find the most-trusted source for a mathematical reference by walking a fixed priority list. The list is meant to be edited — reorder the tiers below if priorities change.

## Priority list

Walk the tiers in order. Use the first one that yields a relevant hit.

1. **Recommended by topic** — `~/Documents/3 Resources/Maths/recommended_by_topic/{Topic}/*.pdf`. Small (~11 PDFs across 7 topic dirs), hand-curated. **If a PDF here covers the query, always use it.**
2. **Sources, curated books** — `~/Documents/3 Resources/Maths/sources/*.pdf` (root only, ~57 PDFs). Well-named `Author - Title.pdf` references.
3. **Sources, deep archives** — `~/Documents/3 Resources/Maths/sources/**/*.pdf` (subdirs: `3b1b/`, `MIT OCW/`, `Mathematics LibreTexts/`, `Open Mathematics Archive/`, author-named folders, ~877 PDFs). Lectures, notes, archived collections.
4. **Web search** — last resort. Cite the URL so the user can vet it.

Recency tiebreaking is intentionally not used: filenames don't carry publication years, and mtime is unreliable as a proxy. Revisit if the naming convention changes.

## Smart search via ragld (preferred starting point)

If the `ragld` daemon is reachable (`GET http://127.0.0.1:8765/ready` → 200), **use it first regardless of tier**. It indexes the same `~/Documents/3 Resources/Maths/` corpus, and the returned chunk `text` is usually enough to answer the question directly — no need to open the PDF at all.

**Query:**

```bash
curl -sS -X POST http://127.0.0.1:8765/rag/query \
  -H 'Content-Type: application/json' \
  -d '{"query": "{the user question}", "top_k": 10}'
```

For known-item lookup (author/year/title) use `/index/search` with `filter: {"subtier": "Maths", "author": [...], "year_min": ...}` instead. Note that `subtier` is populated on `/index/search` results but **not** on `/rag/query` results — apply tier filtering by `path` prefix, not by field.

**Apply the tier priority to results.** ragld doesn't know about `recommended_by_topic/`; enforce it after the fact:

1. If any result's `path` starts with `~/Documents/3 Resources/Maths/recommended_by_topic/`, that's the Tier 1 hit — prefer it over higher-scored results elsewhere. The hand-curated priority rule still wins.
2. Otherwise read results in `score` order. Paths under `sources/*.pdf` (root) are Tier 2; paths under `sources/{subdir}/...` are Tier 3.
3. The same book is often indexed under multiple paths (e.g. a working copy under `Projects/` and the curated copy under `recommended_by_topic/`). Deduplicate by `document_id` *after* the Tier 1 preference is applied.

**Answer from the chunk text when it's sufficient.** Only open the PDF with `Read` when you need surrounding context, examples, or pages adjacent to the chunk. When you do, pass the chunk's `page_number` straight into `Read(pages=...)` — note that `page_number` is the **PDF page index** (including front matter), not the printed page number shown on the page itself. The printed page is often visible at the start of the chunk text (e.g. `52 Chapter 3 Linear Maps`) and is what to use in human-facing citations.

**Fall back to the filename walks below** if the daemon is down, returns nothing relevant, or results clearly miss the question. See the `/ragld` skill for endpoint details and citation conventions.

## How to search each tier (fallback when ragld is unavailable)

**Tier 1** — list the topic dirs once to anchor the mapping:

```bash
ls "$HOME/Documents/3 Resources/Maths/recommended_by_topic/"
```

Map query keywords to a dir (see hints below), then list its contents. For genuinely ambiguous queries (e.g. "metric space" — Topology or Analysis?), check both.

**Tiers 2 & 3** — filename grep by topic/author keyword:

```bash
# Tier 2 (curated root only)
find "$HOME/Documents/3 Resources/Maths/sources" -maxdepth 1 -iname '*{keyword}*.pdf'

# Tier 3 (deep)
find "$HOME/Documents/3 Resources/Maths/sources" -iname '*{keyword}*.pdf'
```

Try several keywords (topic, author, title fragment). If a known author wrote on the topic (e.g. Rudin for analysis, Munkres for topology, Axler for linear algebra), grep by author first.

**Tier 4** — standard web search. Prefer authoritative sources (university course pages, nLab, Wikipedia for vetted classical results, Stacks Project for algebraic geometry, etc.).

## Topic → recommended dir hints

| Query keywords | Dir under `recommended_by_topic/` |
|---|---|
| group, ring, field, ideal, module, Galois | Algebra |
| metric, sequence, series, Lebesgue, Fourier, measure | Analysis |
| functor, morphism, adjoint, monad, limit/colimit | Category Theory |
| vertex, edge, planar, coloring, matching | Graph Theory |
| eigenvalue, vector space, matrix, determinant, dual | Linear Algebra |
| regression, gradient descent, ELBO, neural net, classifier | Machine Learning |
| compact, Hausdorff, open/closed set, continuous, homotopy | Topology |

For a query that legitimately spans two areas (e.g. "spectral theorem" — Analysis and Linear Algebra), check both.

## Output protocol

When you find a relevant source, before extracting content, print the path explicitly so the user can see what you used:

```
**Source:** $HOME/Documents/3 Resources/Maths/recommended_by_topic/Topology/Munkres - Topology.pdf
```

If the chunk text answers the question on its own, just synthesise from it and cite — no `Read` call needed. Otherwise use the Read tool with `pages:` to extract the relevant section:

- If ragld surfaced the source, pass the chunk's `page_number` (PDF page index) straight into `Read(pages=...)`, optionally widened to a small window (e.g. ±3 pages) for context.
- Otherwise (filename-walk fallback), first read the TOC pages (typically pages `1-10` for a textbook) to locate the right chapter/section, then read the specific page range.

If a sidecar TOC file exists, prefer it — e.g. `~/Documents/3 Resources/Maths/Cummings_Real_Analysis_Table_of_Contents.md` is a pre-extracted TOC for the Cummings book. Look for similar `*_Table_of_Contents.md` files at the library root.

If you draw on multiple PDFs, list each source line before the corresponding extract.

## When to fall through to the next tier

Move to the next tier when:

- No filename matches the keyword (after trying topic, author, and title fragments).
- A PDF matches by filename but its TOC shows the topic isn't covered.
- Extracted pages don't actually answer the question (wrong scope, only a passing mention).

State the fall-through briefly (e.g. "no Tier 1 match for `{keyword}`; checking Tier 2") so the user can see the search path.

## When to skip the library entirely

Only skip directly to web search when:

- The user explicitly asks for a web source.
- The topic is outside pure/applied maths (e.g. a software package's API docs).
- The query is about results published after the library was last curated, where a textbook wouldn't help.