Refine guide contract and context reads

[sting8k]

Summary

• Public port of the premium guide/context-read update, without private provider wording.
• Reframe srcwalk guide as an agent evidence contract: srcwalk before broad grep, bounded evidence, and explicit discovery-to-context/show routing.
• Extend show -C/--context-lines to line ranges, resolved sections, and comma-separated show/section targets.
• Clamp context only for comma-separated multi reads: single targets keep the requested -C, multi targets clamp each target to 10.
• Update discover/access/text footer hints to prefer confirmed context targets when structural candidates exist and raw show <path>:<line> -C 10 reads for text/raw hits.

Validation

• git diff --cached --check
• cargo fmt --check
• cargo clippy --locked -- -D warnings
• cargo test --locked --test footer_tips
• cargo test --locked --test intent_first_cli
• cargo test --locked --test path_line
• cargo test --locked --test subcommand_aliases
• debug binary smoke: show --help, structural discover footer, embedded guide

Release note

Parking this PR for a later public release batch. No version bump, tag, release, npm publish, or crates publish is included here.

[greptile-apps]

Greptile Summary

This PR extends show -C/--context-lines from focused single lines to ranges, resolved symbols, and headings, and introduces clamping (max 10) exclusively for comma-separated multi-target reads. It also refines all discovery/access/text footer hints to prefer confirmed context targets when structural candidates exist and raw show <path>:<line> -C 10 reads otherwise.

• Context clamping split: cli_run.rs fast-paths single targets with unclamped -C; the multi-path loop applies min(MAX_MULTI_CONTEXT_LINES). read_multi_section in section.rs applies capped_context_lines for comma-separated --section targets, keeping both call sites consistent.
• Footer routing: append_context_next_targets now returns a bool, and format_search_result_with_header uses it to emit one of two distinct footer hints — routing agents to structural context targets when present, or directly to raw show reads otherwise.
• Artifact note compatibility: The replacement needle in with_artifact_note is updated to track the new footer text from find.rs, preserving artifact-mode hint substitution.

Confidence Score: 5/5

Safe to merge; the single/multi-target clamping split is cleanly implemented at both dispatch layers, footer routing is consistent across all search paths, and the new behaviors are fully covered by integration tests.

The clamping logic correctly separates the single-target fast path (unclamped) from the multi-target loop (clamped) in cli_run.rs, and read_multi_section in section.rs independently enforces the same cap for comma-separated --section targets. The with_artifact_note needle is updated in lockstep with the footer text change in find.rs. The append_context_next_targets bool return is used correctly to branch footer guidance. Four new integration tests in path_line.rs directly exercise the boundary between capped and uncapped contexts, and the existing footer_tips and intent_first_cli tests are updated to match the new hint wording.

No files require special attention.

Important Files Changed

Filename	Overview
src/cli_run.rs	Adds per_target_context clamping to 10 only in the multi-target comma-path loop; single-target (no comma) fast-paths directly with unclamped context_lines, matching the stated contract.
src/read/section.rs	Removes the narrow focused-line-only guard on -C, extends context expansion to ranges, resolved symbols, and headings; read_multi_section applies capped_context_lines (max 10) so multi-section reads stay bounded.
src/search/display/mod.rs	Makes append_context_next_targets return a bool and uses it to select between two footer hint variants, routing agents to confirmed context targets when structural candidates exist, otherwise directly to raw show reads.
src/commands/context.rs	Updates the with_artifact_note replacement needle from the old drill-into-any-hit text to the new read-raw-hit-evidence text, keeping artifact-mode footer substitution working correctly.
tests/path_line.rs	Adds four targeted integration tests covering single-range uncapped context, single-symbol-section uncapped context, multi-section capped-to-10, and comma-separated show locations capped-to-10.
tests/intent_first_cli.rs	Adds assertions that structural hits route to confirmed context targets and text hits route to raw show reads, covering the updated footer routing logic.
src/commands/find.rs	Updates the text-search footer hint from the old wording to read raw hit evidence with srcwalk show.
src/search/access.rs	Footer hint updated to match new read-raw-hit-evidence wording, consistent with all other search output paths.
skills/srcwalk/GUIDE.md	Reframes guide as an evidence contract, adds explicit before-grep routing rules, expands orientation and read-exact sections with comma-OR discovery and multi-target read guidance.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["srcwalk show target -C N"] --> B{target contains comma?}
    B -- No --> C["fast path: context_lines = N unclamped"]
    B -- Yes --> D["multi-target loop: per_target_context = min(N, 10)"]
    C --> F{section type?}
    D --> F
    F -- single line --> G["expand_range(line, line, ctx)"]
    F -- range --> H["expand_range(start, end, ctx)"]
    F -- symbol --> I["expand_range(start, end, ctx)"]
    F -- heading --> J["expand_range(start, end, ctx)"]
    F -- comma sections --> K["read_multi_section: capped_context_lines min(ctx, 10)"]
    G & H & I & J & K --> M["read lines from file, clamp at EOF"]

Loading

_{Reviews (1): Last reviewed commit: "feat: refine guide contract and context ..." | Re-trigger Greptile}