# Search Strategy for the Obsidian Vault (manual fallback)

The three wrapper scripts (`scripts/vault_index.sh`, `scripts/vault_search.sh`,
`scripts/vault_backlinks.sh`) cover the common cases and are the only
commands whitelisted by `/setup`. Use the raw commands below only when the
scripts genuinely don't cover what's needed (e.g. a one-off query shape they
don't support). These are **not** whitelisted, so each one will prompt the
user for confirmation — that's intentional, since they aren't confined to
the configured vault the way the scripts are.

## 1. Get an overview of the structure

```bash
# Folder structure (= topical categories per the user's own convention)
find <vault> -type d -not -path '*/.obsidian*' -not -path '*/.git*' | sort

# Do "index"/"MOC" (Map of Content) files exist? These often bundle links
# on a topic and are a good entry point.
find <vault> -iname '*index*.md' -o -iname '*moc*.md' -o -iname '*overview*.md'
```

## 2. Full-text search

Prefer `rg` (ripgrep), it's much faster and respects `.gitignore`:

```bash
# Basic search, case-insensitive, with file names and line numbers
rg -i -n "<search-term>" <vault> -g '!.obsidian' -g '!.git'

# Only file names of matches (for a quick overview)
rg -i -l "<search-term>" <vault>

# Combine multiple terms (AND via chained greps)
rg -i -l "term-a" <vault> | xargs rg -i -l "term-b"
```

Fallback without ripgrep:

```bash
grep -ril "<search-term>" <vault> --include='*.md'
```

## 3. Use frontmatter and tags

Obsidian frontmatter is a YAML block at the top of a file between `---`.
Tags can live there (`tags: [topic-a, topic-b]`) or inline in the text
(`#topic-a`).

```bash
# All notes with a specific tag in the frontmatter
rg -l '^tags:.*topic-a' <vault>

# All notes with a specific inline tag
rg -l '#topic-a\b' <vault>

# View the frontmatter of a single file (the first 15 lines are usually enough)
head -n 15 "<path-to-file>.md"
```

If the vault uses a consistent tag scheme (e.g. `status/open`,
`system/hostname`), use it as an additional filter dimension, not just
full text.

## 4. Wikilinks and backlinks

`[[NoteName]]` points to another note. For relationships between
topics/entities, backlinks are often more informative than full-text
search:

```bash
# Which notes link to "note-name"?
rg -n '\[\[note-name(\||\]\])' <vault>

# List all outgoing links of a specific note
rg -o '\[\[[^]]+\]\]' "<path-to-file>.md"
```

For troubleshooting-style questions, it's often worth following 1–2 link
hops from the topically closest note (e.g. hardware note → linked
network note → linked incident note) instead of only matching full text
in isolation.

## 5. Large vaults

If there are too many matches: first narrow down to the most plausible
subfolder from the structure overview (step 1), then search in detail.
Don't read every matching file in full by default — check grep context
first (`rg -C 3 ...`) and only open whole files when genuinely needed.