Clean up guides.

Author: samuel-williams-shopify

context/fiber-debugging.md

@@ -169,69 +169,3 @@ The fiber switch command sets up several convenience variables:
 - `$fiber_ptr` - Pointer to `struct rb_fiber_struct`
 - `$ec` - The fiber's execution context
 - `$errinfo` - Exception being handled (if any)
-
-## Best Practices
-
-### Scan Once, Use Indices
-
-After scanning fibers, use indices for all operations:
-
-~~~
-(gdb) rb-fiber-scan-heap           # Scan once
-(gdb) rb-fiber-scan-switch 5       # Switch to fiber #5
-(gdb) rb-stack-trace               # View backtrace
-~~~
-
-The cache persists throughout your GDB session.
-
-### Check Fiber Status
-
-CREATED and TERMINATED fibers may not have valid saved contexts. The scan output shows status:
-
-~~~
-Fiber #5: <T_DATA@...> → <struct rb_fiber_struct@...>
-  Status: TERMINATED           # Won't have useful context
-  
-Fiber #3: <T_DATA@...> → <struct rb_fiber_struct@...>
-  Status: SUSPENDED            # Good candidate for inspection
-~~~
-
-Focus on SUSPENDED and RESUMED fibers for debugging.
-
-### Use Convenience Variables
-
-After switching to a fiber, use the set convenience variables:
-
-~~~
-(gdb) rb-fiber-switch 5
-(gdb) rb-object-print $errinfo      # Pre-set to fiber's exception
-(gdb) rb-object-print $ec->storage  # Fiber-local storage
-~~~
-
-## Common Pitfalls
-
-### Fiber Not Suspended
-
-Only SUSPENDED fibers have fully saved context:
-
-~~~
-Fiber status: CREATED (0)
-  Note: CREATED fibers may not have been suspended yet
-~~~
-
-CREATED fibers haven't yielded yet, so they don't have saved register state.
-
-### Core Dump Limitations
-
-Core dumps capture memory but not CPU registers. Switching to the current fiber may show incomplete stacks. For complete debugging, use live process debugging when possible.
-
-### macOS Code Signing
-
-On macOS, GDB may not be able to attach to running Ruby processes due to code signing restrictions. Core dump analysis works without issues.
-
-## See Also
-
-- {ruby Ruby::GDB::object-inspection Object inspection} for examining fiber storage and exception objects
-- {ruby Ruby::GDB::stack-inspection Stack inspection} for understanding VM frames
-- {ruby Ruby::GDB::heap-debugging Heap debugging} for finding fiber objects
-

context/getting-started.md

@@ -176,27 +176,3 @@ Ruby hashes and arrays can contain nested structures:
 ~~~
 
 The `--depth` flag controls how deep to recurse into nested objects.
-
-## Next Steps
-
-- Learn about {ruby Ruby::GDB::object-inspection inspecting Ruby objects} in detail
-- Explore {ruby Ruby::GDB::fiber-debugging fiber debugging} capabilities
-- Understand {ruby Ruby::GDB::stack-inspection stack analysis} techniques
-- Master {ruby Ruby::GDB::heap-debugging heap navigation} for memory issues
-
-## Requirements
-
-- GDB with Python support (GDB 7.0+)
-- Ruby 3.0+ recommended (works with 2.x with limitations)
-- For best results: Ruby built with debug symbols (`--with-debug-symbols` or install `ruby-debug` package)
-
-## Platform Support
-
-These extensions work on:
-
-- **Linux**: Full support with all features
-- **macOS**: Viewing core dumps works; running processes may require code signing or disabling SIP
-- **BSD**: Should work similar to Linux (untested)
-
-For production debugging, Linux with Ruby debug symbols provides the best experience.
-

context/heap-debugging.md

@@ -349,130 +349,3 @@ end
 ~~~
 
 Low utilization indicates fragmentation.
-
-## Best Practices
-
-### Cache Fiber Results
-
-Don't scan repeatedly in the same session:
-
-~~~
-(gdb) rb-fiber-scan-heap --cache fibers.json    # Scan once
-(gdb) rb-fiber-scan-switch 5                    # Use cached results
-~~~
-
-Later in the same session, just load the cache:
-
-~~~
-(gdb) rb-fiber-scan-heap --cache                # Instant load
-(gdb) rb-fiber-scan-stack-trace-all             # View all backtraces
-~~~
-
-### Limit Scans in Production
-
-For production core dumps with millions of objects:
-
-~~~
-(gdb) rb-fiber-scan-heap --limit 20     # Find first 20 fibers only
-(gdb) rb-heap-scan --limit 100          # Find first 100 objects of any type
-~~~
-
-Often you only need a few objects to diagnose issues.
-
-### Use Object Inspection Together
-
-Combine heap scanning with object inspection:
-
-~~~
-(gdb) rb-heap-scan --type RUBY_T_HASH --limit 5
-Scanning heap for type 0x08, limit=5...
-
-Found 5 object(s):
-
-  [0] $heap0 = <T_HASH@...>
-  [1] $heap1 = <T_HASH@...>
-  ...
-
-(gdb) rb-object-print $heap0 --depth 2
-<T_HASH@...>
-[   0] K: <T_SYMBOL> :key
-       V: <T_FIXNUM> 123
-  ...
-~~~
-
-## Common Pitfalls
-
-### Stale Cache Files
-
-If you load a cache from a different core dump:
-
-~~~
-(gdb) rb-fiber-scan-heap --cache
-Loaded fiber addresses from fibers.json
-Warning: Could not access fiber at 0x7f8a1c800500
-...
-~~~
-
-Delete the cache and rescan:
-
-~~~ bash
-$ rm fibers.json
-~~~
-
-### Scanning Uninitialized VM
-
-If you scan too early during Ruby initialization:
-
-~~~
-(gdb) rb-fiber-scan-heap
-Error: ruby_current_vm_ptr is NULL
-Make sure Ruby is fully initialized and the process is running.
-~~~
-
-Set a breakpoint after VM initialization:
-
-~~~
-(gdb) break rb_vm_exec
-(gdb) run
-(gdb) rb-fiber-scan-heap           # Now works
-~~~
-
-### Memory Errors in Core Dumps
-
-Some heap pages may be unmapped in core dumps:
-
-~~~
-Scanning 5000 heap pages...
-Error reading page 1234: Cannot access memory at address 0x...
-~~~
-
-This is normal - continue with accessible pages.
-
-## Performance Optimization
-
-### Targeted Scanning
-
-Instead of scanning the entire heap, use known addresses:
-
-~~~
-(gdb) rb-fiber-from-stack 0x7f8a1e000000
-Searching for fiber with stack base 0x7f8a1e000000...
-Found fiber: 0x7f8a1c800300
-~~~
-
-### Heap Iteration Caching
-
-The scanner caches GDB type lookups for performance:
-
-- `struct RBasic`
-- `struct RTypedData`
-- `struct rb_fiber_struct`
-
-This makes subsequent iterations much faster.
-
-## See Also
-
-- {ruby Ruby::GDB::fiber-debugging Fiber debugging} for working with found fibers
-- {ruby Ruby::GDB::object-inspection Object inspection} for examining heap objects
-- {ruby Ruby::GDB::stack-inspection Stack inspection} for understanding object references
-

context/object-inspection.md

@@ -206,74 +206,3 @@ Use this to troubleshoot:
 - Missing nested structures
 - Type detection issues
 - Access errors
-
-## Best Practices
-
-### Choose Appropriate Depth
-
-- **Depth 1**: Quick overview, minimal output (default)
-- **Depth 2-3**: Common for most debugging tasks
-- **Depth 5+**: Only for deep investigation, can be verbose
-
-### Work with Core Dumps
-
-The command works perfectly with core dumps since it only reads memory:
-
-~~~
-$ gdb ruby core.12345
-(gdb) source ~/.local/share/gdb/ruby/init.gdb
-(gdb) rb-object-print $ec->errinfo
-~~~
-
-No running process needed!
-
-### Combine with Standard GDB
-
-Use standard GDB commands alongside Ruby extensions:
-
-~~~
-(gdb) info locals              # See C variables
-(gdb) rb-object-print $val     # Interpret as Ruby object
-(gdb) x/10gx $ec->cfp->sp      # Raw memory view
-~~~
-
-## Common Pitfalls
-
-### Accessing Deallocated Objects
-
-If an object address is invalid, you'll see an error:
-
-~~~
-(gdb) rb-object-print (VALUE)0xdeadbeef
-[Error printing object: Cannot access memory at address 0xdeadbeef]
-~~~
-
-Always verify the address is valid before inspecting.
-
-### Depth Too Low
-
-If you see `<T_HASH@...>` or `<T_ARRAY@...>` without expanded content at depth 1:
-
-~~~
-(gdb) rb-object-print $hash       # Shows: <T_HASH@0x...>
-(gdb) rb-object-print $hash --depth 2   # Shows actual content with keys/values
-~~~
-
-Increase `--depth` to see nested structures.
-
-### Missing Debug Symbols
-
-Without debug symbols, some type information may be unavailable:
-
-~~~
-Python Exception <class 'gdb.error'>: No type named RBasic
-~~~
-
-Solution: Install Ruby with debug symbols or use a debug build.
-
-## See Also
-
-- {ruby Ruby::GDB::fiber-debugging Fiber debugging} for inspecting fiber-specific data
-- {ruby Ruby::GDB::stack-inspection Stack inspection} for examining call frames
-- {ruby Ruby::GDB::heap-debugging Heap debugging} for scanning objects
-