docs: Clarify redirect management for same-site vs cross-site moves

Document that GitBook auto-redirects are unreliable and should not be
relied upon. Same-site redirects go in .gitbook.yaml, cross-site
redirects must be configured in the GitBook UI.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: louis-pre

CLAUDE.md

@@ -367,7 +367,10 @@ See the [Architecture](#architecture) section above for the three GitBook site c
 
 ### Redirect Management
 
-Each `.gitbook.yaml` contains redirects maintaining backward compatibility. When restructuring, always add redirects in the appropriate site's config.
+There are two ways to handle redirects. Always use one of these explicitly — do not rely on GitBook's automatic redirects, as they are unreliable.
+
+- **Within the same site:** Add redirects manually in the site's `.gitbook.yaml`.
+- **Across site sections:** `.gitbook.yaml` redirects are scoped to their own site and cannot point to pages in a different site. Cross-site redirects must be configured at the site level from within the GitBook UI.
 
 ---
 
@@ -727,7 +730,7 @@ To follow this guide, you need:
 
 7. **Real-world focus:** Include sandbox credentials, troubleshooting guides, and production checklists. Developers need practical, actionable information.
 
-8. **Link maintenance:** When restructuring, always add redirects in `.gitbook.yaml` to maintain backward compatibility.
+8. **Link maintenance:** When restructuring within a site, add redirects in `.gitbook.yaml`. For cross-site moves, configure redirects in the GitBook UI. Do not rely on GitBook's automatic redirects.
 
 9. **Do not modify file URLs in SUMMARY.md.** Renaming or moving page URLs via SUMMARY.md can break GitBook sync. Use the GitBook UI to rename or move pages instead.
 
@@ -751,7 +754,7 @@ When creating or updating documentation:
 - [ ] Keep paragraphs short (2-3 sentences)
 - [ ] Use active voice and second person
 - [ ] Add entry to SUMMARY.md if creating new page
-- [ ] Update .gitbook.yaml redirects if restructuring
+- [ ] Add explicit redirects if restructuring (`.gitbook.yaml` for same-site, GitBook UI for cross-site — do not rely on auto-redirects)
 
 ### Common Terminology