Docs Navigation

Red Flags - STOP and Reconsider

If you're about to:

• Load full-context.md for a simple question
• Guess file paths instead of reading the index
• Skip the index and go straight to pages
• Load everything "just in case"

STOP -> Follow the Navigation Protocol below -> Then proceed

Workflow

1. CHECKPOINT: Identify what you know (library? section? topic?)
2. Start at the appropriate index level
3. Read index, match keywords to your task
4. Drill down to specific pages
5. Load only the pages you need
6. CHECKPOINT: Is full-context.md justified? (rarely)

Cookbook

Level Selection

• IF: Unsure where to start in the hierarchy
• THEN: Read cookbook/level-selection.md
• RESULT: Start at the right level based on what you know

Keyword Matching

• IF: Searching for documentation by topic
• THEN: Read cookbook/keyword-matching.md
• RESULT: Find relevant pages through index keywords

Efficient Page Loading

• IF: Loading multiple pages or managing token budget
• THEN: Read cookbook/page-loading.md
• RESULT: Minimize token usage while getting needed context

The Hierarchy

ai-docs/
├── _root_index.toon              # Level 0: All categories
├── libraries/
│   ├── _index.toon               # Level 1: All libraries
│   ├── {library}/
│   │   ├── _index.toon           # Level 2: Library sections
│   │   ├── {section}/
│   │   │   ├── _index.toon       # Level 3: Section pages
│   │   │   └── pages/
│   │   │       └── {page}.toon   # Level 4: Page summary
│   │   └── full-context.md       # Everything (escape hatch)

Navigation Protocol

Step 1: Start at the Right Level

Step 2: Read Index, Match Keywords

Each index contains:

• description or purpose - What this level contains
• keywords - Terms for matching your task
• when_to_use - Guidance on when to drill deeper
• Child paths - Where to navigate next

Match your task against keywords:

Task: "Handle LLM retry failures"
Keywords to find: retry, error, failure, fallback, timeout

Navigate:
1. libraries/_index.toon -> "baml" has "llm|structured-output"
2. baml/_index.toon -> common_tasks mentions "error handling"
3. baml/guide/_index.toon -> "error-handling" page has "retry|fallback"
4. baml/guide/pages/error-handling.toon -> Exact info needed

Step 3: Load Only What's Needed

DO:

@ai-docs/libraries/baml/guide/pages/error-handling.toon  # ~400 tokens

DON'T:

@ai-docs/libraries/baml/full-context.md  # ~15,000 tokens

Step 4: Load Multiple Pages if Needed

For complex tasks, load several specific pages:

@ai-docs/libraries/baml/guide/pages/error-handling.toon
@ai-docs/libraries/baml/guide/pages/timeouts.toon
@ai-docs/libraries/baml/reference/pages/retry-policy.toon

Still far cheaper than full-context.md.

Step 5: Use full-context.md Sparingly

Only for:

• Writing comprehensive tutorials
• Major migrations
• Initial deep learning of a library

Index File Structure

Category Index (_index.toon)