---
name: equipment-knowledge-base
description: "Build and maintain a Qdrant knowledge base for vehicles, tools, and equipment — OEM part numbers, maintenance schedules, specs, and cross-references. Free materials only, no shopping links."
version: 1.0.0
category: productivity
tags: [equipment, vehicles, parts, maintenance, qdrant, knowledge-base]
related_skills: [local-vector-memory, qdrant-collection-management, searxng-smart-search]
---

# Equipment Knowledge Base

Build a searchable Qdrant knowledge base for vehicles, tools, and equipment — OEM part numbers, maintenance schedules, fluid specs, cross-references, and dimensions. Designed for queries like "what's the oil filter for my Ranger" or "what oil weight does my tractor take."

## When to Use

- User wants to store manuals, part numbers, and specs for their vehicles/equipment
- User says "I want a collection for my equipment" or "store part numbers for my [vehicle]"
- User wants to query across vehicles ("what oil do all my gas engines use?")

## User Preferences (HARD — do not violate)

- **Free materials only.** Never suggest or purchase paid service manuals without explicit user approval.
- **No shopping links.** The user explicitly said: "I don't need to store shopping links. I just need to make sure part numbers are accurate and correct." Do NOT embed Walmart, Amazon, or other purchase links. Part numbers and cross-references only.
- **Accuracy over breadth.** Part numbers must be sourced from OEM documentation (owner's manual, official parts fiche). Forum cross-references are secondary — flag them as such.
- **Keep pricing details.** When purchase agreements, invoices, or registration emails are found, record the price, serial number, dealer, and date in the part-numbers doc under a `## Purchase Information` section. Include trade-in values and tax breakdowns when available.

## Collection Schema

Single collection: `equipment` (1024-dim, Cosine, Qdrant at 10.0.0.22:6333).

Every point payload should carry:

```json
{
  "text": "The searchable content chunk",
  "vehicle": "2023-polaris-ranger-sp-570",
  "vehicle_label": "2023 Polaris Ranger SP 570 Midsize",
  "vehicle_type": "utv | atv | dirt-bike | zero-turn | tractor | excavator",
  "category": "oem-part-numbers | maintenance-schedule | specifications | cross-reference | forum-knowledge",
  "part_number": "2540086",
  "part_type": "oil-filter | air-filter | spark-plug | belt | tire | battery | fluid | etc",
  "source_type": "oem-manual | forum | parts-fiche",
  "source_url": "https://publications.polaris.com/...",
  "retrieved": "2026-07-12"
}
```

## Vehicle Registry

Maintain a registry in the workspace AGENTS.md. Each vehicle gets a key, label, and type. Example:

| Key | Label | Type |
|-----|-------|------|
| `2023-polaris-ranger-sp-570` | 2023 Polaris Ranger SP 570 Midsize | utv |

## Workflow (per vehicle)

### 1. Research OEM Part Numbers
- Primary source: manufacturer's owner's manual (free PDF or online portal)
- Search SearXNG for: `[year] [make] [model] owner's manual part numbers`
- Pull the specifications page and maintenance section via `web_url_read`
- Extract: spark plug type/gap, oil type, fluid types and capacities, tire sizes/pressures
- **IMPORTANT: Owner's manuals typically do NOT list filter/belt part numbers.** Polaris and John Deere owner's manuals list specs but not consumable part numbers. Those are in the separate parts catalog. For filters and belts, cross-reference from:
  - Manufacturer's "quick parts guide" or "replacement parts guide" PDF (e.g., Deere's `z515e-with-48-54-60-inch-deck.pdf`)
  - Brand-specific forums (prcforum.com for Polaris, etc.)
  - Aftermarket kit listings that confirm fitment across years
  - **Always flag cross-referenced numbers** — do not present them as OEM-verified

### 2. Cross-Reference (Secondary)
- Search forums (prcforum.com for Polaris, etc.) for cross-reference threads
- Extract aftermarket equivalents (WIX, NAPA, Mobil 1, K&N, etc.)
- Flag as "forum-sourced" — not OEM-verified

### 3. Maintenance Schedule
- Pull the full maintenance schedule from the owner's manual
- Include intervals, fluid capacities, torque specs
- Note severe-use caveats (50% interval reduction)

### 4. Write Structured Markdown
- One doc for part numbers + specs
- One doc for maintenance schedule
- Store in `~/workspace/equipment/` as `<vehicle>-part-numbers.md` and `<vehicle>-maintenance.md`
- Include source URL and retrieval date

### 5. Ingest into Qdrant (IMMEDIATELY after writing)
- Use `mcp_better_qdrant_add_documents` for BOTH markdown files in the same turn
- Target collection: `equipment`
- Embedding service: `ollama`
- **Do NOT wait for the user to say "go" or "ingest."** After writing the .md files, immediately call add_documents for both. The user explicitly said "automatically add all to collections."

### 6. Verify Queryability
Run 1-2 test queries (not 3 — keep it fast):
- "what is the oil filter part number for [vehicle]"
- "[vehicle] tire pressure" or "[vehicle] oil capacity"

Scores 0.5+ are good. Below 0.4 means chunking or query mismatch.

### 7. Search Email for Purchase Documents
Before building docs for a new vehicle, search the user's email for purchase agreements, invoices, and registration notices. These contain serial numbers, pricing, dealer info, and exact model configurations that owner's manuals don't.

- Use `himalaya envelope list` with `from <dealer domain>` and `from <salesperson>` queries
- Search across ALL folders — purchase docs may be in INBOX, RECEIPTS, or custom folders
- Download PDF attachments with `himalaya attachment download` and extract with pymupdf (or tesseract fallback for scanned docs)
- Record findings in the part-numbers doc under `## Purchase Information`
- Key fields: dealer name, date, serial number/VIN, price, trade-in, tax, warranty terms
- If no purchase docs found, note it explicitly — don't fabricate

## Querying the KB (Answering User Questions)

When the user asks a question about their equipment (e.g., "what tools for an oil change," "what's the interval for X"):

1. **Query Qdrant first.** Search the `equipment` collection for what the KB already has — part numbers, maintenance schedules, fluid specs.
2. **Identify the gap.** The KB has specs and schedules but typically does NOT have step-by-step procedures, tools lists, or torque sequences. Those live in the owner's manual or Polaris help center articles.
3. **Web search to fill the gap.** Search SearXNG for the specific procedure (e.g., `"[year] [model] oil change procedure tools"`). Polaris help center articles (KA-XXXXX) often have the full tools list and steps.
4. **Combine and present.** Merge Qdrant data (part numbers, fluids, capacities) with web-sourced procedure details (tools, steps, torque specs). Cite both sources.

### When the user asks for a product on a specific retailer (Walmart, Amazon, etc.)

- **Search the retailer directly** — use `site:walmart.com` or `site:amazon.com` in the SearXNG query. General web searches return forum threads and third-party sites; retailer-specific searches surface actual product listings.
- **Verify fitment before recommending.** Cross-check the product's listed compatibility against the vehicle's known specs (model year, trim level, chassis type). Many listings claim broad compatibility that is wrong (e.g., "fits Ranger 570" but only fits Full Size, not SP 570 midsize).
- **Walmart product pages are Cloudflare-blocked for `web_url_read`** — you'll get a "Robot or human?" captcha page. Use the SearXNG search snippet for price, specs, and part number. The snippet is usually sufficient.
- **For oil change kits:** confirm the quart count matches the vehicle. The 570 takes 2 qts (kit #2890056 or #2202166). The XP 1000 takes 2.5 qts (kit #2879323). Recommending the wrong kit means the user gets the wrong oil quantity.

## Pitfalls

- **Cloudflare blocks on parts sites.** polaris.com, partzilla.com, rockymountainatvmc.com all use aggressive Cloudflare bot detection. The browser tool (Browserbase) has its own IP separate from the host VPN — it may be blocked even when the host VPN is fresh. Use SearXNG `web_url_read` for Polaris's publications portal (publications.polaris.com) which is NOT Cloudflare-protected. For parts fiche sites, fall back to SearXNG search snippets if direct access is blocked.
- **Polaris help center (polaris.com/en-us/off-road/owner-resources/help-center/) is Cloudflare-blocked.** `web_url_read` on KA-XXXXX articles returns 403. However, SearXNG search snippets for these articles often contain the full procedure text (tools list, steps, torque values). Use the search snippet as the primary source when the article itself is blocked — the snippet is usually complete enough to answer the question.
- **SearXNG is in a separate LXC (10.0.0.8:8888), not behind the host VPN.** It has its own IP. If SearXNG returns empty results, the issue is with SearXNG's engines, not the host VPN. The `web_search` tool and `web_extract` go through the host VPN — if SearXNG works but these don't, the host VPN IP is likely flagged.
- **NordVPN reconnect for fresh IP.** The host runs NordVPN 5.2.0. If sites block the host IP, reconnect: `nordvpn disconnect && nordvpn connect us <different_city>`. Agent is authorized to reconnect without asking. Any other NordVPN settings changes require user permission. Current settings: NordLynx, kill switch on, firewall on, post-quantum on, allowlisted ports 53 + 11434, subnet 34.36.133.0/24.
- **Don't confuse owner's manual with service manual.** The free owner's manual has specs, fluid capacities, and maintenance schedules. The paid service manual has repair procedures, torque specs for every bolt, wiring diagrams. The user only wants free materials — owner's manual is sufficient for the KB.
- **Owner's manuals often don't list filter/belt part numbers.** Polaris manuals list spark plug type, oil type, and fluid capacities but NOT oil filter, air filter, or drive belt part numbers. Those are in the separate Polaris parts catalog (paid or dealer-only). Cross-reference from forums and aftermarket kit listings, but FLAG these as cross-referenced, not OEM-verified. Example: "Oil Filter (OEM): 2540086 (cross-referenced — same filter used across Polaris 570/1000 models)".
- **Part number supersessions.** OEMs sometimes supersede part numbers (e.g., air filter 2521372 → 7082037). Note both, with the current number first.
- **Forum cross-references may be for different years.** A 2014 Ranger 570 cross-reference thread may not apply to a 2023 SP 570. Verify compatibility before embedding.
- **Spark plugs vary by engine serial number.** Some manufacturers (John Deere) don't list a single plug number in the quick parts guide — it depends on the specific engine. Note this caveat and tell the user to check the engine blower housing for the serial number.
- **CAT parts are serial-number specific.** Caterpillar parts catalogs require the machine serial number prefix (e.g., BDH for 301.5). Fuel and hydraulic filter part numbers vary by serial number. Always tell the user to confirm with a CAT dealer using their serial number. The engine oil filter (150-4140 for C1.1/3003) is one of the few parts that crosses multiple models.
- **Some engines have no replaceable oil filter.** Small Honda engines (CRF50F, CRF70F, XR50R, XR70R) use a centrifugal oil screen that must be cleaned during oil changes — there is no cartridge or spin-on filter to replace. Note this explicitly so the user doesn't go looking for a part that doesn't exist.
- **Oil change intervals can vary by model number within the same year.** The 2024 Polaris Sportsman 570 has some model numbers (A24SEE57B1, etc.) that use a 100-hour oil change interval while others use 200-hour. Check the owner's manual for model-number-specific notes and flag this for the user.
- **Deck/belt size variants on mowers.** Zero-turn mowers often have multiple deck sizes (48"/54"/60"). Confirm which deck the user has before recording blade and belt part numbers. The parts guide may list all variants — only record the one that matches.
- **Don't fabricate part numbers.** If a number can't be confirmed from an official or well-established source, say so explicitly. The user values accuracy over completeness.
- **marker-pdf is unreliable on Python 3.13.** `pip install marker-pdf` installs but `marker_single` fails with cascading missing deps (pdftext → ftfy → surya). When you need OCR on scanned PDFs and marker-pdf is broken, use the tesseract fallback: pymupdf → PNG export → pytesseract. See `references/tesseract-fallback.md` for the recipe.
- **PDFs from Deere.com are text-based.** The John Deere replacement parts guides and filter overviews on deere.com are text-layer PDFs — pymupdf extracts them directly, no OCR needed. Only scanned dealer invoices/agreements need OCR.
- **`web_url_read` returns raw PDF binary for PDF URLs.** When fetching PDFs from deere.com or similar, `web_url_read` returns the raw PDF bytes, not extracted text. Download with `curl -sL -o /tmp/file.pdf "<url>"` then extract with pymupdf instead.
- **`web_url_read` section extraction fails on XML content.** publications.polaris.com serves owner's manuals as XML, not markdown. The `section` parameter silently returns "not found" because the heading structure doesn't match. Workaround: fetch without a `section` filter and parse the raw content, or rely on SearXNG search snippets which often contain the full procedure text.
- **Base model SP 570 headlight bulbs are a trap.** The OEM part #4010253 cross-references to 881/886 PG13 bulbs, but these do NOT physically fit the base model connector. H13/9008 dual-beam bulbs also don't fit (base model is single-beam, 2-prong). The only guaranteed path: (1) pull the existing bulb and read the stamped number, or (2) buy the OEM LED assembly kit #2889877. Do NOT recommend a bulb type without the user confirming the stamped number on their existing bulb. See `references/ranger-sp570-headlight-bulbs.md` for the full failure history.

## Workspace

- Path: `~/workspace/equipment/`
- AGENTS.md: scopes the collection, declares vehicle registry, lists out-of-scope collections
- Source markdown files live here before ingestion

## Related Skills

- `local-vector-memory` — Qdrant stack setup, embedder config, MCP tools
- `qdrant-collection-management` — collection CRUD, schema, registry
- `searxng-smart-search` — search defaults for parts/manual research
- `himalaya` — email CLI for searching purchase documents and invoices

## References

- `references/email-purchase-search.md` — pattern for searching Gmail for purchase agreements, invoices, and registration notices via Himalaya CLI
- `references/ranger-sp570-example.md` — example part-numbers doc
- `references/tesseract-fallback.md` — OCR recipe when marker-pdf is broken
- `references/polaris-cross-model-reference.md` — Polaris part number cross-model compatibility
- `references/nordvpn-reference.md` — NordVPN reconnect procedure
- `references/ranger-sp570-oil-change.md` — Ranger SP 570 oil change: tools, supplies, drain plug specs, torque, intervals
- `references/ranger-sp570-accessory-wiring.md` — Ranger SP 570 ACC wire location, pulse bar vs terminal block, fuse, wiring guidance
- `references/ranger-sp570-aftermarket-exhaust.md` — Aftermarket exhaust options for SP 570 midsize (very limited — Big Gun only potential fit)
- `references/ranger-sp570-headlight-bulbs.md` — Headlight bulb replacement: what doesn't fit (H13, 881/886, Sixty61), confirmed bulb type (9006/HB4), OEM LED upgrade kit #2889877, forum consensus
- `references/ranger-sp570-front-gearcase-fluid.md` — Front gearcase (Demand Drive) fluid change: capacity, tools, torque, Walmart link, interval
- `references/ranger-sp570-under-hood-power-setup.md` — Under-hood accessory power distribution: fuse block, wiring, complete Walmart shopping list, installation strategy