docs: update README, commands.json, VFS docs for v0.3.8

[BANANASJIM]

User description

Summary

• Add callstacks command entry to commands.json
• Update section usage with --write flag
• Update passes usage with --deps/--dot/--graph flags
• Add pixel/, attachments/, used-by VFS routes to vfs.astro
• Add Capture file category to README command table

Test plan

• npx astro build passes (10 pages built)
• pixi run check clean (2488 tests, lint, mypy)

---

PR Type

Documentation

---

Description

• Add callstacks command to commands.json and README

• Update section command with --write flag support

• Update passes command with --deps, --dot, --graph flags

• Expand VFS documentation with pixel/, attachments/, used-by routes

• Add Capture file category to README command table

---

Diagram Walkthrough

flowchart LR
  A["Documentation Files"] --> B["commands.json"]
  A --> C["README.md"]
  A --> D["vfs.astro"]
  B --> B1["Add callstacks command"]
  B --> B2["Update passes flags"]
  B --> B3["Update section with --write"]
  C --> C1["Add Capture file category"]
  D --> D1["Add pixel/ route"]
  D --> D2["Add attachments/ route"]
  D --> D3["Add used-by route"]

Loading

File Walkthrough

Relevant files

Documentation

commands.json Add callstacks command and update command flags                    docs-astro/src/data/commands.json Update passes command usage to include --deps, --dot, --graph flags Update section command help text from "Extract" to "Read or write" Update section command usage to include --write parameter Add new callstacks command entry with help and usage information +9/-3      README.md Add Capture file category to command table                              README.md Add new "Capture file" category row to command table List capture file commands: sections, section, callstacks, gpus, thumbnail +1/-0      vfs.astro Expand VFS documentation with new routes                                  docs-astro/src/pages/docs/vfs.astro Add pixel/ VFS route with / structure for pixel history Add attachments/ route under passes with color and depth targets Add used-by route under shaders showing EIDs that use shader Update passes route parameter from to Add shader info, disasm, and used-by routes +13/-3

---

Summary by CodeRabbit

• New Features

  • Added callstacks command to resolve CPU call stacks for events.
  • Extended section command to support writing named section contents.
  • Added new command-line options (--deps, --dot, --graph) to passes command.

• Documentation

  • Updated command reference and virtual file system documentation structure.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates command documentation and VFS filesystem structure information. It adds new options to the passes command, extends the section command with write functionality, documents a new callstacks command, and expands the VFS tree to include pixel history, per-shader directories, and pass attachment structures.

Changes

Cohort / File(s)	Summary
Command Documentation README.md, docs-astro/src/data/commands.json	Added new line documenting "Capture file" command group in README. Updated command definitions: passes with new --deps, --dot, --graph flags; section with write capability (--write <FILE> option); introduced new callstacks command with CPU callstack resolution functionality.
VFS Structure Documentation docs-astro/src/pages/docs/vfs.astro	Expanded VFS tree documentation under draws/ to include pixel history (descriptors/, pixel/x/y paths). Renamed passes/<id>/ to passes/<name>/ and added attachments/ folder with color targets and depth target. Enhanced shaders/ section with per-shader id subdirectories containing info, disasm, and used-by entries.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs(readme): rewrite README + fix CI badge stats #103: Updates README command listings and related command metadata entries alongside this PR's documentation changes.
• feat(passes): add pass dependency DAG with --deps and --dot flags #155: Implements the rdc passes command flags (--deps, --dot, --graph) that are documented in this PR's command definitions.

Poem

A rabbit hops through docs with glee, 🐰
Adding passes, callstacks, history—
VFS trees grow more complete,
Commands documented, all so neat!
The docs now dance in harmony! 📚✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main objective of the PR: updating documentation files (README, commands.json, and VFS docs) for version 0.3.8.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/v038-update

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Use unique ID for path parameter Revert the VFS path for render passes from back to to ensure a unique and unambiguous identifier, preventing potential issues with non-unique pass names. docs-astro/src/pages/docs/vfs.astro [43-46] --│ └── &lt;id&gt;/ -+│ └── &lt;name&gt;/ +-│ └── &lt;name&gt;/ ++│ └── &lt;id&gt;/ +│ └── attachments/ +│ ├── color0, color1… # color output targets +│ └── depth # depth target [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a potential ambiguity introduced by using a non-unique <name> instead of a unique <id> for a path parameter, which could lead to incorrect or unpredictable behavior for users.	Medium
	Add missing capture commands Add the new gpus and thumbnail commands to the commands.json file to keep it synchronized with the README.md documentation. docs-astro/src/data/commands.json [408-413] { "name": "callstacks", "id": "callstacks", "help": "Resolve CPU callstack for an event.", "usage": "rdc callstacks [--eid INTEGER] [--json]" +}, +{ + "name": "gpus", + "id": "gpus", + "help": "List GPU statistics from a capture file.", + "usage": "rdc gpus [--json]" +}, +{ + "name": "thumbnail", + "id": "thumbnail", + "help": "Generate a thumbnail image from a capture file.", + "usage": "rdc thumbnail [--output <FILE>]" } Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that the commands.json file is missing commands that were added to the README.md, and adding them improves documentation consistency.	Medium
	Clarify if command argument is required Update the usage string for the callstacks command to indicate that the --eid argument is required by changing [--eid INTEGER] to --eid . docs-astro/src/data/commands.json [408-413] { "name": "callstacks", "id": "callstacks", "help": "Resolve CPU callstack for an event.", - "usage": "rdc callstacks [--eid INTEGER] [--json]" + "usage": "rdc callstacks --eid <INTEGER> [--json]" } Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies an ambiguity in the command's usage documentation and proposes a change that makes the argument requirement clear and consistent with other commands.	Low
More

[coderabbitai]

🧹 Nitpick comments (1)

README.md (1)

191-191: Consider aligning category name with commands.json.

The README uses "Capture file" but commands.json defines this category as "Capture Metadata" (line 380). This minor inconsistency could cause confusion when cross-referencing documentation. Consider using a consistent name across both files.

The command list itself is complete and matches the commands.json definitions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 191, The README line that labels the command category as
"Capture file" should be made consistent with the category name in commands.json
("Capture Metadata"); update the README entry that currently reads "Capture
file" to "Capture Metadata" (or vice versa if you prefer commands.json) so both
files use the exact same category string, and verify the header and the list
entry (`sections`, `section`, `callstacks`, `gpus`, `thumbnail`) reflect the
chosen name.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@README.md`:
- Line 191: The README line that labels the command category as "Capture file"
should be made consistent with the category name in commands.json ("Capture
Metadata"); update the README entry that currently reads "Capture file" to
"Capture Metadata" (or vice versa if you prefer commands.json) so both files use
the exact same category string, and verify the header and the list entry
(`sections`, `section`, `callstacks`, `gpus`, `thumbnail`) reflect the chosen
name.

---

ℹ️ Review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 71c7285 and 3d5af03.

📒 Files selected for processing (3)

• README.md
• docs-astro/src/data/commands.json
• docs-astro/src/pages/docs/vfs.astro

[greptile-apps]

Greptile Summary

Documentation updates for v0.3.8 accurately reflect recent codebase changes. All command definitions, flags, and VFS routes were verified against actual implementation in src/rdc/commands/ and src/rdc/vfs/router.py.

• Added callstacks command with correct --eid and --json flags
• Updated section command to document new --write flag for writing section contents
• Updated passes command to include --deps, --dot, and --graph flags
• Documented new VFS routes: pixel/<x>/<y> for pixel history, attachments/ under passes, and info/disasm/used-by under shaders
• Corrected passes route parameter from <id> to <name> matching router implementation

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Documentation-only changes that accurately reflect the implementation. All command flags, usage strings, and VFS routes were verified against source code. Tests passed (npx astro build and pixi run check). No code changes mean zero runtime risk.
• No files require special attention

Important Files Changed

Filename	Overview
README.md	Added "Capture file" category with correct commands (sections, section, callstacks, gpus, thumbnail)
docs-astro/src/data/commands.json	Updated passes, section, and added callstacks command with correct flags matching actual implementation
docs-astro/src/pages/docs/vfs.astro	Added pixel/, attachments/, shader routes, corrected passes parameter from <id> to <name>

_{Last reviewed commit: 3d5af03}