Refine guide contract and context reads

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to srcwalk are documented here.
 
 ## Unreleased
 
+### Changed
+- Extended `show -C/--context-lines` to line ranges, resolved sections, and comma-separated show/section targets; comma-separated multi reads clamp each target to 10 context lines.
+- Updated discover next-step guidance to prefer confirmed `context` targets when structural candidates exist and raw `show <path>:<line> -C 10` reads for text hits.
+- Reframed the embedded agent guide as an evidence contract with explicit `srcwalk`-before-`rg` routing and comma-separated literal OR discovery guidance.
+
 ## [1.0.0] - 2026-05-24
 
 ### Highlights

README.md

@@ -343,7 +343,7 @@ Scopes on this page: src/evidence (2), src/commands (0)
 (~101 tokens)
 
 > Next: 25 more matches available. Continue with --offset 2 --limit 2.
-> Next: drill into any hit with `srcwalk <path>:<line>`.
+> Next: choose a confirmed context target above, or read raw hit evidence with `srcwalk show <path>:<line> -C 10`.
 
 ---
 # Search: "Anchor" in 2 scopes — 2 matches (1 definitions, 1 usages)
@@ -381,7 +381,7 @@ Scopes on this page: src/evidence (2), src/commands (0)
 (~418 tokens)
 
 > Next: 38 more matches available. Continue with --offset 2 --limit 2.
-> Next: drill into any hit with `srcwalk <path>:<line>`.
+> Next: choose a confirmed context target above, or read raw hit evidence with `srcwalk show <path>:<line> -C 10`.
 ```
 </details>
 

skills/srcwalk/GUIDE.md

@@ -1,11 +1,33 @@
-# srcwalk — agent routing policy
+# srcwalk — agent evidence contract
 
-Use srcwalk before shell search for code navigation. Keep `--scope` narrow.
-Use raw `rg` only for final text confirmation.
+Default to srcwalk first for code-structure work. It is the contract for finding exact code evidence, next reads, and bounded claims before shell search.
+
+Keep `--scope` narrow. Use raw `rg`, `read`, `fd`, or shell filesystem tools only for final text/regex confirmation, filesystem metadata, generated-output cleanup, or when srcwalk lacks structural support. If you bypass srcwalk for a code claim, say why.
+
+## Contract
+
+1. Start from intent, not files: orient with `overview`, find candidates with `discover`, then pick one exact target.
+2. Follow srcwalk evidence: run `context`, `show`, `trace`, `deps`, `assess`, `review`, or `compare` from paths, ranges, symbols, and `> Next:` commands.
+3. Cite bounded evidence: base conclusions on srcwalk path:line/range output and preserve its `source`, `kind`, `confidence`, and `caveat` limits.
+4. Do not overclaim: text/file hits are literal evidence; structural hits are navigation evidence; neither proves runtime behavior, security, correctness, aliases, types, or dynamic dispatch unless explicitly supported.
+5. Verify after edits: use `srcwalk review --staged` or the relevant srcwalk route before tests; use `rg` only for final raw text or regex confirmation.
+
+Do not infer definitions, usages, callers, dependencies, or code paths from shell path lists or broad grep alone.
+
+## Before grep/rg
+
+Stop if you are about to do this for code navigation:
+
+- `rg "functionName"` -> use `srcwalk discover 'functionName' --scope <dir>`.
+- `rg "functionName\("` -> use `srcwalk trace callers functionName --scope <dir>`.
+- `rg "^import|^use"` -> use `srcwalk deps <file>`.
+- `srcwalk show <file>` without discovery -> use `srcwalk discover <query> --scope <dir>` first, unless you already know the exact file evidence you need.
+
+Why: grep gives raw text matches that often require extra filtering. srcwalk gives scoped candidates, typed evidence, and exact next commands. Use `rg` after srcwalk when you need raw regex confirmation.
 
 ## Default workflow
 
-Use this command flow for broad, unfamiliar, or risky code tasks:
+Use the smallest subset of this flow that proves the task. For broad, unfamiliar, or risky code work, start here:
 
 ```text
 request / bug / feature question
@@ -35,115 +57,82 @@ When output includes `source`, `kind`, `confidence`, or `caveat`, treat them as
 
 ## Routes
 
-### Orient an unfamiliar area
+### Orient and choose a target
 
-Do not start orientation with shell `tree`, shell `find`, repeated `ls`, or repo-wide `rg`.
+Do not start broad code navigation with shell `tree`, shell `find`, repeated `ls`, or repo-wide `rg`.
 
 ```bash
 srcwalk overview --scope <dir>
-```
-
-Use auto depth first. Do not pass `--depth` first. Explicit `--depth N` is strict.
-
-`[relations]` are static local dependency groups, not runtime calls.
-`[outbound deps]` imports targets outside `--scope`.
-
-Drill down with candidate intake, then context.
-
-```bash
+srcwalk overview --scope <dir> --symbols
 srcwalk discover <query> --scope <dir>
 srcwalk discover '<glob>' --as file --scope <dir>
-srcwalk discover <term> --as text --scope <dir>
+srcwalk discover 'foo,bar,baz' --match any --as text --scope <dir>
+srcwalk discover <field> --as access --scope <dir>
 srcwalk context <symbol> --scope <dir>
 ```
 
-`discover` searches only inside `--scope`; narrow scopes can hide definitions.
+Use auto overview depth first; explicit `--depth N` is strict. `[relations]` are static local dependency groups, not runtime calls. `[outbound deps]` imports targets outside `--scope`.
 
-`--filter kind:<label>` is exact: `fn`, `class`, `mod`, `impl`, `base`, `usage`, `text`, `comment`.
+`discover` only searches inside `--scope`; narrow scopes can hide definitions. After a first pass, use `--expand=3`, `--filter kind:fn`, or `--exclude 'tests/**'` only when the output is too broad.
 
-Intent inference:
+Intent inference: path-like globs infer file discovery; punctuation/path comma lists infer literal Text OR; symbol globs stay symbol search. Add `--as symbol|file|text` when ambiguous.
 
-- path-like globs such as `*.rs` or `src/**/*.ts` infer file discovery;
-- punctuation/path comma lists such as `req.body,fetch` infer literal Text OR;
-- symbol globs such as `*Controller` remain symbol search. Add `--as symbol` if ambiguous.
+For multiple literal text terms, use comma OR: `srcwalk discover 'foo,bar,baz' --match any --as text --scope <dir>`. Do not run separate grep commands first.
 
-Text discovery: `--match any --as text` is comma literal OR; broad results roll up files first.
-`--match all` is same-file co-occurrence, not semantic relation proof.
+Text discovery is literal evidence. `--match any --as text` is comma literal OR; `--match all` is same-file co-occurrence, not semantic relation proof.
 
-If discover prints `## Confirmed next context targets`, run one of those `context` commands.
+If discover prints `## Confirmed next context targets`, those are structural candidates from the match context; run one that matches your intent. If it only prints raw hit drilldowns, use `srcwalk show <path>:<line> -C 10` first. `discover <field> --as access` is syntax only: no runtime order, type proof, alias proof, or call relation proof.
 
-Use `discover <field> --as access` for field/member write/reset/read groups.
-It is syntax only, not runtime order, type proof, alias proof, or call relation proof.
+### Understand and read exact evidence
 
-### Understand one selected target
-
-Use `context` for one known target. It emits Flow Map facts, call neighborhoods, and exact `> Next:` commands.
-Run it before review or trace chains.
+Use `context` for one known target before review or trace chains. Use `show` for exact source after srcwalk gives a path/line/range, or when you already know the target.
 
 ```bash
 srcwalk context <file>:<symbol>
 srcwalk context <file>:<line-or-range>
 srcwalk context <symbol> --scope <dir>
-```
-
-Read exact evidence after srcwalk gives a path/line/range, or when you already know the target.
-Do not pass a bare file to `context`; use `show` or root reads.
-
-```bash
-srcwalk show <path>:123 -C 20
+srcwalk show <path>:123 -C 10
 srcwalk show 'a.rs:12,b.rs:40-55'
 srcwalk show <path> --section <symbol>
-srcwalk <path>
+srcwalk show <path> --section '120-140,SomeSymbol' -C 10
+srcwalk show README.md --section '# Install'
 srcwalk <path>:123-150
 ```
 
-### Inspect call direction
+Do not pass a bare file to `context`; use `show` or root reads. `-C` uses the requested context for one target; comma-separated multi reads clamp each target to 10 lines.
 
-Use `trace callers` for upstream call sites. Do not grep `foo(`.
+### Trace calls
 
-Use `--count-by receiver|caller|file|args|path` for grouped summaries.
+Use `trace callers` for upstream call sites and `trace callees` for downstream calls. Do not grep `foo(`.
 
 ```bash
 srcwalk trace callers <symbol> --scope <dir>
-srcwalk trace callers <symbol> --depth 2 --scope <dir>
+srcwalk trace callers <symbol> --scope <dir> --expand=3
 srcwalk trace callers <symbol> --count-by receiver --scope <dir>
-```
-
-Use `trace callees` for downstream calls.
-
-```bash
+srcwalk trace callers <symbol> --depth 3 --max-frontier 20 --max-edges 100 --skip-hubs log,emit --scope <dir>
 srcwalk trace callees <symbol> --scope <dir>
 srcwalk trace callees <symbol> --detailed --scope <dir>
+srcwalk trace callees <symbol> --detailed --filter receiver:client --scope <dir>
 srcwalk trace callees <symbol> --depth 2 --scope <dir>
 ```
 
-Drill down from trace with exact call-site reads or context on a caller/callee.
-
-```bash
-srcwalk show <path>:123 -C 20
-srcwalk context <caller-or-callee> --scope <dir>
-```
+Drill down with exact call-site reads or `context` on a caller/callee.
 
 ### Inspect file coupling
 
-Use `deps` for imports, links/assets, local symbol deps, and dependents.
-Run it before file moves, deletes, or coupling explanations. Do not grep import/use/require/link tags.
+Use `deps` for imports, links/assets, local symbol deps, and dependents. Run it before file moves, deletes, or coupling explanations.
 
 ```bash
 srcwalk deps <file>
-```
-
-Drill down from deps with exact import/link reads or context on a related source target.
-
-```bash
 srcwalk show <path>:123-150
 srcwalk context <related-symbol> --scope <dir>
 ```
 
+Do not grep import/use/require/link tags for dependency claims.
+
 ### Assess edit risk
 
-Use `assess` before changing, removing, renaming, or publicizing a symbol.
-It is fast blast-radius triage; verify risky results with trace callers/deps.
+Use `assess` before changing, removing, renaming, or publicizing a symbol. It is blast-radius triage; verify risky results with trace callers/deps.
 
 ```bash
 srcwalk assess <symbol> --scope <dir>
@@ -158,55 +147,36 @@ Use `review` for change sets. It composes changed evidence with bounded Flow Map
 ```bash
 srcwalk review
 srcwalk review --staged
+srcwalk review --staged --limit 5 --offset 5
 srcwalk review HEAD~1..HEAD --scope src
-```
-
-Drill down from review with context on a changed symbol or exact changed-range reads.
-
-```bash
 srcwalk context <changed-symbol> --scope <dir>
 srcwalk show <path>:123-150
 ```
 
 ### Compare two known targets
 
-Use `compare` for two known source targets.
-It reports shared/only structural evidence, not equivalence, runtime, security, or correctness proof.
+Use `compare` for two known source targets. It reports shared/only structural evidence, not equivalence, runtime, security, or correctness proof.
 
 ```bash
 srcwalk compare <file>:<symbol-a> <file>:<symbol-b>
 srcwalk compare <symbol-a> <symbol-b> --scope <dir>
-srcwalk show <path>:123-150
 ```
 
 ### Confirm raw text or filesystem metadata
 
-For raw regex and regex flags, use `rg`; srcwalk text discovery is literal evidence plus navigation context.
-
-Use shell `find`/`fd` only for filesystem metadata:
-permissions, mtimes, empty dirs, symlinks, binary assets, generated outputs, cleanup lists.
+Use `rg` for raw regex and regex flags; srcwalk text discovery is literal evidence plus navigation context. Use shell `find`/`fd` only for filesystem metadata: permissions, mtimes, empty dirs, symlinks, binary assets, generated outputs, cleanup lists.
 
 ```bash
 rg '<regex>' <dir>
 find <dir> -type f -mtime -1
-find <dir> -empty
 fd -HI -t f -x stat
 ```
 
-Do not infer definitions, usages, callers, deps, or code paths from shell path lists.
-Do not convert identifiers into paths without evidence.
-
-```bash
-srcwalk discover '<identifier>' --scope <dir>
-srcwalk discover '*<name>*' --as file --scope <dir>
-```
+Do not infer definitions, usages, callers, deps, or code paths from shell path lists. Do not convert identifiers into paths without evidence.
 
 ## Artifact routes
 
-Exact artifact reads/scopes may auto-enable artifact mode.
-Use `--artifact` for broad generated, bundled, minified, or binary-like traversal.
-
-Prefer exact footer commands. Artifact output is byte-span evidence only.
+Exact artifact reads/scopes may auto-enable artifact mode. Use `--artifact` for broad generated, bundled, minified, or binary-like traversal. Prefer exact footer commands. Artifact output is byte-span evidence only.
 
 ```bash
 srcwalk <artifact-file> --artifact
@@ -216,12 +186,8 @@ srcwalk dist/app.min.js --artifact  # artifact-level outline for bundled/minifie
 
 ## Supported structural languages
 
-Code/source structure: Rust, TypeScript/TSX, JavaScript, Python, Go, Java/Scala/Kotlin, C/C++.
-Also Ruby, PHP, C#, Swift, Elixir, CSS/SCSS/Less.
-
-Documents: HTML/HTM plus Markdown-style `.md`, `.mdx`, `.rst` fallback.
-Covers sections, elements, code blocks, links, assets.
+Code/source structure: Rust, TypeScript/TSX, JavaScript, Python, Go, Java/Scala/Kotlin, C/C++, Ruby, PHP, C#, Swift, Elixir, CSS/SCSS/Less.
 
-Treat document output as navigation evidence, not rendered or runtime proof.
+Documents: HTML/HTM plus Markdown-style `.md`, `.mdx`, `.rst` fallback. Covers sections, elements, code blocks, links, assets. Treat document output as navigation evidence, not rendered or runtime proof.
 
 Unsupported languages still work for exact reads; structural facts may be unavailable.

src/cli.rs

@@ -46,7 +46,7 @@ pub(crate) struct Cli {
 }
 
 pub(crate) const ROOT_HELP: &str = "\
-Start here:\n  srcwalk guide                         Full embedded, version-matched agent guide for agents\n\nCommon:\n  srcwalk overview                      Show repo orientation and dependency groups\n  srcwalk context <symbol-or-file:line> Understand one known target\n  srcwalk trace callers <symbol>        Show who calls a symbol\n  srcwalk trace callees <symbol>        Show what a symbol calls\n  srcwalk deps <file>                   Show imports and dependents\n  srcwalk assess <symbol>               Heuristic blast-radius triage\n  srcwalk review <range-or-staged>      Review a change set with Flow Map evidence\n  srcwalk compare <target-a> <target-b> Compare two known source targets structurally\n  srcwalk discover <query>              Find candidate symbols/usages/text\n  srcwalk discover <glob> --as file     Find files by glob\n  srcwalk show <path>:<line> -C 20      Read exact evidence with extra line context\n  srcwalk <path>                        Read a file smartly\n  srcwalk <path>:<line>                 Read around a line\n  srcwalk version                       Show version; add --check for latest";
+Start here:\n  srcwalk guide                         Full embedded, version-matched agent guide for agents\n\nCommon:\n  srcwalk overview                      Show repo orientation and dependency groups\n  srcwalk context <symbol-or-file:line> Understand one known target\n  srcwalk trace callers <symbol>        Show who calls a symbol\n  srcwalk trace callees <symbol>        Show what a symbol calls\n  srcwalk deps <file>                   Show imports and dependents\n  srcwalk assess <symbol>               Heuristic blast-radius triage\n  srcwalk review <range-or-staged>      Review a change set with Flow Map evidence\n  srcwalk compare <target-a> <target-b> Compare two known source targets structurally\n  srcwalk discover <query>              Find candidate symbols/usages/text\n  srcwalk discover <glob> --as file     Find files by glob\n  srcwalk show <path>:<line> -C 10      Read exact evidence with extra line context\n  srcwalk <path>                        Read a file smartly\n  srcwalk <path>:<line>                 Read around a line\n  srcwalk version                       Show version; add --check for latest";
 
 pub(crate) const GUIDE: &str = include_str!("../skills/srcwalk/GUIDE.md");
 
@@ -148,7 +148,7 @@ pub(crate) struct ShowCmd {
     /// Show explicit raw first page (capped at 200 lines / 5k tokens).
     #[arg(long)]
     pub(crate) full: bool,
-    /// Lines of context before and after a line target.
+    /// Lines of context before and after a line/range/section target; multi targets clamp to 10.
     #[arg(short = 'C', long = "context-lines", value_name = "N")]
     pub(crate) context_lines: Option<usize>,
 }

src/cli_run.rs

@@ -6,6 +6,7 @@ use crate::output;
 use srcwalk::ArtifactMode;
 
 const MAX_SHOW_TARGETS: usize = 8;
+const MAX_MULTI_CONTEXT_LINES: usize = 10;
 
 fn display_path(path: &Path) -> String {
     let path = path.display().to_string();
@@ -867,6 +868,7 @@ fn run_show(
     }
 
     let per_target_budget = budget.map(|cap| (cap / targets.len() as u64).max(1));
+    let per_target_context = context_lines.map(|count| count.min(MAX_MULTI_CONTEXT_LINES));
     let mut outputs = Vec::with_capacity(targets.len());
     for target in targets {
         outputs.push(srcwalk::run_path_exact_with_artifact_and_context(
@@ -876,7 +878,7 @@ fn run_show(
             per_target_budget,
             full,
             artifact,
-            context_lines,
+            per_target_context,
             cache,
         )?);
     }

src/commands/context.rs

@@ -190,7 +190,7 @@ pub(crate) fn with_artifact_note(output: String, artifact: ArtifactMode) -> Stri
             ),
         )
         .replace(
-        "> Next: drill into any hit with `srcwalk <path>:<line>`.",
+        "> Next: read raw hit evidence with `srcwalk show <path>:<line> -C 10`.",
         "> Next: drill artifact hits with `srcwalk <path> --artifact --section <symbol|bytes:start-end>`.",
     );
     let caveat = evidence_source_caveat_for(EvidenceSource::Artifact).unwrap_or("");

src/commands/find.rs

@@ -213,7 +213,7 @@ pub(crate) fn run_text_or_filtered_with_artifact(
     );
     if total_found > 0 {
         let rendered = render_next_actions(&[NextAction::guidance(
-            "drill into any hit with `srcwalk <path>:<line>`.",
+            "read raw hit evidence with `srcwalk show <path>:<line> -C 10`.",
             "text-or hit drilldown",
             40,
         )]);

src/read/full.rs

@@ -126,7 +126,8 @@ pub fn read_file_with_budget_and_context(
     if context_lines.is_some() && section.is_none() {
         return Err(SrcwalkError::InvalidQuery {
             query: path.display().to_string(),
-            reason: "--context-lines requires a path:line target or --section line".to_string(),
+            reason: "--context-lines requires a path:line, path:range, or --section target"
+                .to_string(),
         });
     }