Address second Copilot review round: docs accuracy and stale comment

- output.ts: update inline comment — seg.line/seg.col are now absolute
  file line numbers resolved by api.ts (not fragment-relative)
- output-formats.md: replace nested-backtick prose with fenced code block
  example to avoid malformed Markdown rendering
- output-formats.md: reword Query title section to distinguish format
  (Markdown/JSON) from output-type (repo-only/repo-and-matches)
- output-formats.md: remove #L2 anchor from JSON example url field —
  buildJsonOutput() emits m.htmlUrl without anchoring to line
- README.md: qualify matchedText/line/col as 'when segment data is
  available' to avoid overstating the JSON schema guarantee

Author: shouze

README.md

@@ -36,7 +36,7 @@ github-code-search query "TODO" --org my-org
 - **Per-repository aggregation** — results grouped by repo, not as a flat list; fold/unfold each repo to focus on what matters
 - **Keyboard-driven TUI** — navigate with arrow keys, toggle selections, filter by file path, confirm with Enter — without leaving the terminal
 - **Fine-grained selection** — pick exactly the repos and extracts you want; deselected items are recorded as exclusions in the replay command
-- **Structured output** — Markdown document with a `# Results for` query heading, GitHub deeplinks and the exact matched token per extract; or machine-readable JSON with `matchedText`, `line` and `col` fields — ready to paste into docs, issues or scripts
+- **Structured output** — Markdown document with a `# Results for` query heading, GitHub deeplinks and the exact matched token per extract; or machine-readable JSON that, when segment data is available, includes `matchedText`, `line` and `col` fields — ready to paste into docs, issues or scripts
 - **Team-prefix grouping** — group results by team prefix (e.g. `platform/`, `data/`) using `--group-by-team-prefix`
 - **Replay command** — every session produces a one-liner you can run in CI to reproduce the exact same selection without the UI
 - **Regex search** — use `/pattern/flags` syntax for pattern-based searches; the CLI derives a safe API query and filters results locally

docs/usage/output-formats.md

@@ -32,11 +32,15 @@ github-code-search "useFeatureFlag" --org fulll --no-interactive
 
 :::
 
-Each extract link points directly to the matching line on GitHub. When the GitHub API returns the exact matched token, it is appended inline in backticks (e.g. `` : `useFeatureFlag` ``).
+Each extract link points directly to the matching line on GitHub. When the GitHub API returns the exact matched token, it is appended inline after the link — for example:
+
+```text
+  - [ ] [src/foo.ts:3:5](https://github.com/org/repo/blob/main/src/foo.ts#L3): `useFeatureFlag`
+```
 
 ## Query title
 
-Every output (both Markdown and repo-only) is prefixed with a `# Results for` heading that identifies the search query. When active qualifiers are present, they are appended after a `·` separator:
+Every output — in both Markdown and JSON formats, and for both `repo-only` and `repo-and-matches` output types — is prefixed with a `# Results for` heading that identifies the search query. When active qualifiers are present, they are appended after a `·` separator:
 
 ```text
 # Results for "useFeatureFlag" · including archived · excluding templates
@@ -67,7 +71,7 @@ github-code-search "useFeatureFlag" --org fulll --format json --no-interactive
       "matches": [
         {
           "path": "src/middlewares/featureFlags.ts",
-          "url": "https://github.com/fulll/auth-service/blob/main/src/middlewares/featureFlags.ts#L2",
+          "url": "https://github.com/fulll/auth-service/blob/main/src/middlewares/featureFlags.ts",
           "line": 2,
           "col": 19,
           "matchedText": "useFeatureFlag"

src/output.ts

@@ -247,8 +247,9 @@ export function buildMarkdownOutput(
     for (const m of matches) {
       // Use VS Code-ready path:line:col as link text and anchor the URL to the
       // line when location info is available (GitHub #Lline deeplink).
-      // Position is fragment-relative (GitHub Code Search API does not return
-      // absolute line numbers).
+      // seg.line/seg.col reflect absolute file line numbers resolved by api.ts
+      // (falling back to fragment-relative positions when raw content is
+      // unavailable).
       const seg = m.textMatches[0]?.matches[0];
       if (seg) {
         const matchedText = seg.text ? `: ${mdInlineCode(seg.text)}` : "";