p24-infra Docs

obsidian-vault-navigation

4 min read

Obsidian Vault Navigation — Playbook

Status: STABLE

What triggers this

You need to find infra/ops documentation in docs/ cheaply — by following links — instead of grepping full file contents across the whole vault. docs/ is a real Obsidian vault (see docs/playbooks/obsidian-vault-access.md), but it has two structurally different parts, and using the wrong navigation method for each wastes time and tokens.

Pre-conditions

  • You are working inside the p24-infra repo, with docs/ present in the checkout.
  • No special access needed — this is a read-only navigation method, works identically for a local session and for a headless worker (bms-4) that only has git clone.

Steps

There are two tiers, depending on what you’re looking for.

Tier 1 — architecture / ops / design knowledge

  1. Start at docs/index.md — the Obsidian vault home. Not docs/README.md: that file exists only for GitHub’s own file browser to render something sensible when a human opens the repo on github.com, and is explicitly excluded from the Quartz static-site build. docs/index.md is the real entry point — it links to all 18 numbered perspective hubs.

    Get-Content C:\code_2026\p24-infra\docs\index.md

  2. Find the relevant row in the “18 Perspectives” table (e.g. 06-secrets, 10-server-maintenance, 04-monitoring) and read only that one docs/NN-topic/README.md hub.

  3. In that hub’s “Key Documents” table, find the single target file the question is actually about and read only that file.

    Three reads total (index.md → perspective hub → target doc) instead of a directory-wide grep across dozens of unrelated files.

Tier 2 — operational runbooks / incident fixes

  1. Go straight to docs/playbooks/README.md — the flat grouped index for docs/playbooks/ (see docs/playbooks/README.md itself for the full category list: Secrets & Credential Rotation, SOPS Operations, Per-Service Credential/Token Rotation, MongoDB, Pinbox24 W3/W4, Queue Dispatcher & Worker Infra, Servers, Monitoring & Alerting, Networking, Supabase, and more).
  2. Find the relevant category section and open the target playbook directly from its table row.

docs/playbooks/ is deliberately flat and prefix-named (e.g. w3-*, sops-*, *-credential- rotation) rather than wikilinked — the README.md index built in this playbook, not [[wikilinks]] scattered across 323 individual files, is what makes the directory navigable. Do not attempt to “fix” this by retrofitting all playbooks with [[wikilinks]] between each other — that exact idea was evaluated on 2026-08-05 and explicitly deferred as a large, low-urgency retrofit with no concrete consumer at the time (see docs/playbooks/obsidian-vault-access.md §4). The flat index is the lighter-weight solution that was actually shipped.

Verification

  • Confirm the 18-perspective index in docs/index.md resolves to real files — it already does, this is existing, working infrastructure: 
    Get-Content C:\code_2026\p24-infra\docs\index.md | Select-String '\[\[.*README\]\]'
  • Confirm docs/playbooks/README.md exists and a spot-check of its links resolve: 
    Test-Path C:\code_2026\p24-infra\docs\playbooks\README.md
# Spot-check a handful of linked files actually exist:
Select-String -Path C:\code_2026\p24-infra\docs\playbooks\README.md -Pattern '\[([a-zA-Z0-9_.-]+\.md)\]\(\1\)' -AllMatches |
  Select-Object -First 5

Rollback

Not applicable — this is a read-only navigation method, nothing to undo. If docs/playbooks/ README.md itself is ever found to be stale or wrong, fix it directly per docs/playbooks/playbook-lifecycle.md Situation 2 (update the index, don’t route around it).

Common mistakes

  • Using docs/README.md as the vault entry point: wrong — it’s a GitHub-browsing convenience file, excluded from the Quartz build. Always start at docs/index.md for real navigation.
  • Grepping all of docs/playbooks/*.md content when the topic is already covered by a perspective hub: if the question is architectural/design (“how does the queue dispatcher work”), Tier 1 (perspective hub) is usually the right answer, not a keyword grep across 323 runbooks.
  • Assuming every subdirectory of the vault is equally linked just because .obsidian/ exists at the vault root: .obsidian/ config applies to the whole vault, but link density is not uniform. docs/playbooks/ had zero inbound perspective links until this playbook and docs/playbooks/README.md were added — check that a specific directory actually has a working index/hub before assuming it’s navigable the same way as the rest of the vault.
  • docs/playbooks/obsidian-vault-access.md — what’s installed (skills, plugins) and what’s deliberately not installed (obsidian-cli) for Obsidian access in this repo
  • docs/playbooks/playbook-lifecycle.md — how to write/modify/retire a playbook
  • docs/playbooks/README.md — the Tier 2 flat index this playbook describes navigating
  • docs/index.md — the Tier 1 vault home this playbook describes navigating

Graph View

Backlinks