Pyramid Reading with pyramid-read

Use pyramid-read via Bash instead of the Read tool for any markdown file.
This keeps context usage low. Load only what's relevant.

Requires Bash access. If you don't have it, respond with NEEDS_CONTEXT: requires Bash permission to run pyramid-read

Quick start

pyramid-read docs/spec.md               # list all headers
pyramid-read docs/spec.md "## Overview" # read a specific section in full
pyramid-read docs/                      # survey folder — all .md files (headers ≤ depth 2) + all subfolders recursively

Workflow: survey/list → read. Load only what's relevant.

Example: progressive document reading

# Step 1: survey the docs folder
pyramid-read docs/
# → docs/spec.md
# →
# → # Backend Server Spec
# → ## Overview
# → ## Authentication
# → ## Request Lifecycle
# →
# → docs/guides/
# → docs/guides/advanced/
# → docs/reference/

# Step 2: list all headers in a specific file
pyramid-read docs/spec.md
# → # Backend Server Spec
# → ## Overview
# → ## Authentication
# → ### Sellers
# → ## Request Lifecycle

# Step 3: read the relevant section
pyramid-read docs/spec.md "## Authentication"
# → ## Authentication
# →
# → ### Sellers
# → - Register via Firebase...

Example: error handling

pyramid-read spec.md "## Nonexistent"
# stderr: Error: section not found: "## Nonexistent"
# exit code: 1

pyramid-read missing.md
# stderr: Error: file not found: missing.md
# exit code: 1

Notes

• Headings inside code fences (```) are ignored — they are not treated as document structure
• Expand mode is deep: it captures the heading plus all nested subsections
• List mode returns all headers at every depth
• Folder mode returns headers at depth ≤ 2 only (h1 and h2)
• Folder mode also lists all subdirectories recursively (with trailing slash) after the file blocks, sorted depth-first