Docs contradict implementation: `rtk init` claims `gh api` saves 26%, but `run_api` is intentional 0% passthrough

Summary

rtk init writes documentation into CLAUDE.md claiming rtk gh api yields ~26% savings, but run_api is an intentional passthrough at 0% — as its own source comment says. Since rtk init writes this text directly into a coding agent's instruction file, the agent is told a compression exists that deliberately does not.

This is a docs bug, not a request to compress gh api. The passthrough behavior is correct and should stay.

The contradiction

src/cmds/git/gh_cmd.rs:981 — the implementation, deliberate and well-reasoned:

fn run_api(args: &[String], _verbose: u8) -> Result<i32> {
    // gh api is an explicit/advanced command — the user knows what they asked for.
    // Converting JSON to a schema destroys all values and forces Claude to re-fetch.
    // Passthrough preserves the full response and tracks metrics at 0% savings.
    run_passthrough("gh", "api", args)
}

src/hooks/init.rs:185 — what rtk init writes into CLAUDE.md:

rtk gh api              # Compact API responses (26%)

docs/usage/FEATURES.md:472:

| `rtk gh api <endpoint>` | Reponse API compacte | ~26% |

The section header in the generated block also reads ### GitHub (26-87% savings), so the 26% floor of that range is the gh api entry.

Measured (rtk 0.43.0, macOS arm64, gh 2.x)

The 514 KB case rules out a size threshold. The repo view case confirms the gh compression path itself works — api is simply (and correctly) not on it.

rtk gain reports these invocations at 0%, consistent with the source comment's "tracks metrics at 0% savings".

Verified against v0.44.2 source that run_api is unchanged, so this is not fixed in the current release.

Why it matters more than a typical docs typo

rtk init writes this into CLAUDE.md / AGENTS.md — the file an agent reads as ground truth every session. An agent that believes gh api is compressed will not reach for --jq, and will hand full API responses to the model. In my case that was a 514 KB response passed byte-for-byte while the agent believed it had been compacted.

There's also a secondary trap worth a doc note: rtk json looks like the natural substitute, but it sorts keys alphabetically and truncates to 21 (verified: 85 keys → 21, 40 keys → 21; --depth doesn't affect this). It does print ... +N more keys, so nothing is hidden — but on a GitHub API response the 21 survivors are all URL fields (allow_forking, archive_url, assignees_url, …) while name, stargazers_count, license, language, topics are all in the dropped set.

Related

Prior issues show gh api compression was implemented and then walked back for correctness — #31 (added it), #199 (truncation broke programmatic use), #311 (--jq returned int/string placeholders instead of real values), #370, #235. The current passthrough looks like the resolution of that history; the docs just didn't follow.

Distinct from #446 / #1484, which are about gh search. Note that #446's description assumes "gh api may already have patterns" — the same misconception this doc line creates.

Suggested fix

In src/hooks/init.rs and docs/usage/FEATURES.md, replace the 26% claim with the actual behavior and the thing that does save tokens:

rtk gh repo view <repo> # Compact repo view
# NOTE: `rtk gh api` is intentional passthrough (0%) — compressing API JSON
# destroys values and forces a re-fetch. Filter at the source with --jq instead:
#   rtk gh api repos/o/r --jq '.stargazers_count, .license.spdx_id'

Happy to open a PR if that framing works for you.

Environment

• rtk --version: 0.43.0 (behavior verified unchanged in v0.44.2 source)
• macOS Darwin 25.5.0, arm64, zsh
• Hook: rtk hook claude registered as PreToolUse / Bash

Read src/cmds/git/gh_cmd.rs:981 first to confirm that run_api is intentional passthrough, then inspect the generated text in src/hooks/init.rs:185 and the table in docs/usage/FEATURES.md:472. Done means both documentation locations accurately describe rtk gh api as 0% passthrough and point users toward source filtering with --jq, without changing the implementation.