Imported from ssoj13/squarebob-rs (
AGENTS.md). Install upstream withnpx skills add ssoj13/squarebob-rs. Copyright stays with the author.
AGENTS.md
Bug-hunt operating notes
This is the squarebob-rs Rust package and squarebob binary (Cargo.toml:1-13). Source paths below were checked on 2026-09-23. On 2026-09-23, the first user-authorized python bootstrap.py b release build failed in upstream vfx-io with E0599. After the upstream EXR fix and a local egui_dock TabViewer::id implementation (src/app/dock.rs:105-110), a second release build succeeded. No tests ran; see plan11.md for that build sequence and the warnings observed then. The completed systemic repairs are tracked in plan12.md; plan13.md records the subsequent warning and CPU-picking fixes. Read DIAGRAMS.md for Mermaid dataflows. Neither pass ran tests or a visual comparison.
Primary constraints for future agents:
- Keep owned scan data on the UI side.
DirEntry.rectusesCell; scanner/cache workers transfer owned trees through channels. - Use
ScanRoot's canonical path and native-path ID for operational identity. Itsdisplaystring preserves user spelling for UI/history (src/path_key.rs:6-62). Cache and exclusion validation now use the canonical identity; inspectplan12.mdfor the source review and outstanding verification. - The standard walker calls
fscan_rs::scan_standard; its entry callback builds the owned tree and reports progress (src/scanner.rs:288-421). It reconstructs omitted parent directories from yielded paths (src/scanner.rs:302,315-366). The Windows NTFS adapter callsfscan_rs::scan_ntfs_tree_with_progressand converts its tree to ownedDirEntrynodes (src/scanner_ntfs.rs:62-150).Cargo.toml:179andCargo.lock:3337-3345pin the private GitHubfscan-rsrevisionc33d4474b5004ec047ecd065f96f6a53addbc97e. Its public NTFS tree API preserves typedScanFailurevariants (../fscan-rs/src/ntfs.rs:394-433). - A scan generation owns a
ScanSession, progress receiver, and separate terminal receiver. Replacement cancels and retires the prior session;poll_scandiscards stale generation/root outcomes (src/scanner.rs:85-153;src/app/scan_orchestration.rs:38-69,456-528). CacheServiceowns ordered cache I/O, generation watermarks, and atomic replacement. Only complete live scans queue a cache store (src/cache.rs:107-245,893-905;src/app/scan_orchestration.rs:237-250). Flat cache v4 still carries a serialized display-path field for decoding, but runtime validation uses canonical root ID (src/cache.rs:39-48,523-535,786-797).render_core::gpu::GpuContext::newis the wgpu device setup source.main.rs:145-185passes its instance/device/queue to eframe and app renderers.- Use central
readback_texture,map_readback, andmap_buffer_readhelpers. They returnResultfor layout, map, poll, channel, mapped-range, and host-allocation failures (crates/render-core/src/lib.rs:551-805,807-839). - Keep native 2D/3D textures on the eframe device. CPU pixels/readback serve 2D CPU, fallback, and screenshot paths (
src/app/treemap_view.rs:20-98;src/app/mod.rs:608-647). - Trace
#[allow(dead_code)], TODO/FIXME, feature gates, and platform stubs before deleting them. Preserve unrelated worktree changes.
Workspace inventory
Cargo.toml:15-37 lists 20 members: squarebob-core, pt-core, bvh-gpu, pt-megakernel, pt-wavefront, pt-mats, render-core, render-shared, render-3d, media-encoder, xtask, treemap, pt-denoise-oidn, gpu-mem, standard-surface, squarebob-widgets, pt-material, playa-ae, egui-colorpicker, and color-pipeline. Earlier file counts and bug-hunt artifact claims were historical snapshots.
Application dataflow
CLI -> cli::parse_args: Result; main exits 2 on invalid input
-> GpuContext::new -> eframe WgpuSetup::Existing -> App::new
-> App::start_scan
-> ScanRoot(display, canonical path, id)
-> exclusions::load -> valid policy or visible warning + edit guard
-> CacheService::Load(generation) -> optional cache preview
-> scanner::spawn(generation, fscan-rs standard | NTFS MFT)
-> NTFS unavailable at selection: choose standard backend
-> NTFS unavailable: terminal warning + standard fallback
-> NTFS cancelled: Cancelled; fatal error: Failed
-> Progress + Terminal(Completed | Partial | Cancelled | Failed)
-> App::poll_scan: reject stale generation/id; install tree
-> complete scan: CacheService::Store -> atomic cache write
-> display_root -> App::ui_treemap
-> 2D CPU -> pixel buffer -> egui texture
-> 2D GPU -> GpuRenderer2D -> native egui_wgpu texture
-> 3D raster/PT -> Renderer3D -> native egui_wgpu texture
-> optional screenshot -> capture_viewport(Result) -> save_png(Result)
-> success: mark taken/optional exit; failure: retry/dismiss UI
Sources: src/main.rs:19-28,145-185; src/app/scan_orchestration.rs:299-363,456-528; src/app/treemap_view.rs:20-98; src/app/screenshot.rs:12-77.
Scan and cache codepath
start_scan
|-- retire old scan; clear presentation; advance generation
|-- ScanRoot::from_input -> canonical path + stable id
|-- exclusions::load; warn and block edits on unreadable policy
|-- CacheService::load(generation, root)
`-- scanner::spawn(generation, root, backend)
|-- fscan-rs standard OR NTFS MFT; fallback only if NTFS unavailable
|-- scanner::finish_build: sort tree + derive stats
|-- complete tree: serialize_cache_ref on scan worker
`-- terminal channel delivers typed ScanOutcome
poll_scan
|-- poll ordered cache events; gate by generation + root_id
|-- drain progress and terminal channels; gate by generation + identity
|-- install_tree -> rebuild_display_tree + invalidate layout/render
`-- complete outcome -> queue CacheService::store -> atomic_file::write
Sources: src/app/scan_orchestration.rs:38-69,130-250,299-528; src/scanner.rs:134-235; src/cache.rs:90-245,273-307,893-905.
Rendering and readback codepath
App::ui_treemap
|-- native 2D GPU: render_2d_callback -> render_to_texture -> egui_wgpu
|-- native 3D: render_3d_callback -> render_to_view -> prepare_scene
| |-- empty scene: clear color/object ID; reset picking/UI selection; skip OIDN
| |-- raster passes + active object-ID picking; remap selection by path on rebuild
| |-- shift-drag marquee: path baseline -> active instance IDs per preview/commit
| `-- path tracing + current Object ID for outline + optional OIDN denoise
`-- legacy: render_treemap -> CPU 2D OR GPU/3D pixel readback -> egui upload
3D readback also uses prepare_scene + shared pass encoding
GPU pixel readback
-> TextureReadbackLayout::new (checked geometry)
-> readback_texture (reusable staging buffer)
-> map_readback -> map_buffer_read
-> callback Result/channel -> fallible host allocation -> ReadbackError or packed Vec<u8>
Sources: src/app/treemap_view.rs:20-98,1034-1217,1373-1430; src/app/mod.rs:569-659; crates/render-3d/src/lib.rs:467-590,1430-1510; crates/render-3d/src/renderer3d/render.rs:18-60,112-138; crates/render-core/src/lib.rs:551-805,810-839. The old double-unwrap diagram described a previous implementation.
Media export codepath
Comp::get_frame
|-- video: encode_sequence_from_comp
| -> crop/conditional tonemap
| -> VideoEncoder::open/push/finish
| -> codec conversion + MovWriter + private partial file + commit
`-- image sequence: encode_image_sequence
-> target-depth tonemap (U16 retains float precision)
-> PNG/TIFF/TGA/EXR/JPEG writer
-> TIFF selected compression; TGA selected RLE
Sources: crates/media-encoder/src/dialogs/encode/encode.rs:1148-1280,1657-1762,1769-1937; crates/media-encoder/src/dialogs/encode/video.rs:66-118. The TIFF/TGA compression and U16 conversion changes are reviewed in plan12; plan11 retains the original findings. App image-sequence capture currently supplies RGBA8 (src/app/image_sequence.rs:257-267), so its U16 output cannot regain lost source precision.
Current bug-hunt focus
plan13.md records the bug-hunt pass at 6562a5280c42195345dee2fef36c59254ee7d894; it resolved the four glam warnings recorded in plan12.md. The scanner migration now uses a pinned GitHub revision. cargo check and the scanner unit tests passed on Windows; large-scan performance and other platforms remain unverified. plan14.md records the earlier documentation checkpoint and publication update. plan15.md records the typed NTFS outcome repair, the cleanup of incidental lockfile changes, and current CI/runtime verification gates. The current repair passed cargo metadata --locked --no-deps and cargo check --workspace --locked -q on Windows with empty check stderr; no tests were run for it. plan12.md retains the systemic repair and runtime gates; plan11.md retains the original evidence and wider workspace audit backlog. Check historical source references against the current worktree before use.
GitNexus — Code Intelligence
GitNexus was fully reindexed on 2026-09-23 after the bug-hunt edits (5,720 nodes and 13,170 relationships reported). Check graph freshness before relying on query/impact results after further edits; reanalyze when needed. Earlier graph counts are historical.
Call
graph_statuswhen freshness matters. Usereanalyze(incremental) orgitnexus-rs analyze(full).detect_changesdoes not re-index.
Always Do
- Check graph freshness with
graph_statusbefore trusting query/impact on a repo you have been editing. - MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run
gitnexus_impact({target: "symbolName", direction: "upstream"})and report the blast radius (direct callers, affected processes, risk level) to the user. - MUST run
gitnexus_detect_changes()before committing to verify your changes only affect expected symbols and execution flows. - MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
- When exploring unfamiliar code, use
gitnexus_query({query: "concept"})to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use
gitnexus_context({name: "symbolName"}). - Update the graph with
reanalyze(incremental) orgitnexus-rs analyze(full).detect_changesdoes not re-index. - Uncommitted edits while commit is fresh:
reanalyzewithscope: "unstaged", or rungitnexus-rs watchin a terminal.
Never Do
- NEVER edit a function, class, or method without first running
gitnexus_impacton it. - NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use
gitnexus_renamewhich understands the call graph. - NEVER commit changes without running
gitnexus_detect_changes()to check affected scope.
Resources
| Resource | Use for |
|---|---|
gitnexus://repo/squarebob-rs/context |
Codebase overview, check index freshness |
gitnexus://repo/squarebob-rs/clusters |
All functional areas |
gitnexus://repo/squarebob-rs/processes |
All execution flows |
gitnexus://repo/squarebob-rs/process/{name} |
Step-by-step execution trace |
Tool discovery
The old .claude/skills/gitnexus/ links are absent from this worktree. Discover the currently available GitNexus MCP tools or the gitnexus-rs CLI help before use; check graph status and reanalyze if the index is stale. The policy above applies whenever the graph is available.