docs: group nav into sections and fix placeholder troubleshooting for users who need to navigate docs or debug missing content

Reorganize the flat 9-page nav into Guide/Reference/Help sections
with navigation.sections enabled for clear sidebar grouping. Fix
the troubleshooting page's incorrect claim that unresolved placeholders
appear as raw text — the code replaces unmatched names with empty
string, so the real symptom is silently missing content.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

docs/troubleshooting.md

@@ -142,16 +142,20 @@ If `ralph status` warns that a check has neither a `run.*` script nor a `command
 
 ## Context and instruction issues
 
-### Placeholders not resolving
+### Placeholder produces no output
 
-If you see raw `{{ contexts.my-context }}` text in the agent's output, the placeholder name doesn't match any discovered context. Check:
+If a `{{ contexts.my-context }}` placeholder silently disappears (the prompt has nothing where you expected content), the context name doesn't match any discovered context. Ralphify replaces unmatched named placeholders with an empty string — you won't see raw placeholder text. Check:
 
 1. The directory name matches: `.ralph/contexts/my-context/CONTEXT.md`
 2. The placeholder uses the exact directory name: `{{ contexts.my-context }}`
 3. The context is enabled (check with `ralph status`)
+4. If the context has a command, verify the command produces output by running it manually
 
 Same rules apply for `{{ instructions.name }}`.
 
+!!! note "Raw placeholder text still visible?"
+    If you see literal `{{ contexts.name }}` in the agent's output, the placeholder syntax wasn't recognized — usually a typo in the keyword (e.g. `{{ context.name }}` instead of `{{ contexts.name }}`). It must be `contexts` (plural) and `instructions` (plural).
+
 ### Context command failing
 
 Run the context command manually:

mkdocs.yml

@@ -26,8 +26,10 @@ theme:
   features:
     - content.code.copy
     - content.code.annotate
+    - content.tabs.link
     - navigation.instant
     - navigation.tracking
+    - navigation.sections
     - navigation.top
     - navigation.footer
     - search.suggest
@@ -60,11 +62,14 @@ extra:
 
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md
-  - How It Works: how-it-works.md
-  - Writing Your Prompt: prompts.md
-  - Cookbook: cookbook.md
-  - Primitives: primitives.md
-  - Configuration & CLI: cli.md
-  - FAQ: faq.md
-  - Troubleshooting: troubleshooting.md
+  - Guide:
+    - Getting Started: getting-started.md
+    - How It Works: how-it-works.md
+    - Writing Your Prompt: prompts.md
+    - Cookbook: cookbook.md
+  - Reference:
+    - Primitives: primitives.md
+    - Configuration & CLI: cli.md
+  - Help:
+    - FAQ: faq.md
+    - Troubleshooting: troubleshooting.md